Category Archives: cmdlet

AuthenticodeSignature, cmdlet, Get

Get-AuthenticodeSignature

NAME
    Get-AuthenticodeSignature

SYNOPSIS
    Gets information about the Authenticode signature in a file.

SYNTAX
    Get-AuthenticodeSignature [-FilePath] <string[]> [<CommonParameters>]

DESCRIPTION
    The Get-AuthenticodeSignature cmdlet gets information about the Authenticode signature in a file. If the file is not signed, the information is retrieved, but the fields are blank.

PARAMETERS
    -FilePath <string[]>
        Specifies the path to the file being examined. Wildcards are permitted, but they must lead to a single file. The parameter name (“FilePath”) is optional.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, ByPropertyName)
        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.String
        You can pipe a string that contains a file path to Get-AuthenticodeSignature.

OUTPUTS
    System.Management.Automation.Signature
        Get-AuthenticodeSignature returns a signature object for each signature that it gets.

NOTES

        For information about Authenticode signatures in Windows PowerShell, see about_Signing.

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

    C:\PS>Get-AuthenticodeSignature -FilePath C:\Test\NewScript.ps1

    Description
    ———–
    This command gets information about the Authenticode signature in the NewScript.ps1 file. It uses the FilePath parameter to specify the file.

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

    C:\PS>Get-AuthenticodeSignature test.ps1, test1.ps1, sign-file.ps1, makexml.ps1

    Description
    ———–
    This command gets information about the Authenticode signature in the four files listed at the command line. In this command, the name of the FilePath parameter, which is optional, is omitted.

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

    C:\PS>Get-ChildItem $pshome\*.* | ForEach-Object {Get-AuthenticodeSignature $_} | where {$_.status -eq “Valid”}

    Description
    ———–
    This command lists all of the files in the $pshome directory that have a valid Authenticode signature. The $pshome automatic Variable contains the path to the Windows PowerShell installation directory.

    The command uses the Get-ChildItem cmdlet to get the files in the $pshome directory. It uses a pattern of *.* to exclude directories (although it also excludes files without a dot in the filename).

    The command uses a pipeline operator (|) to send the files in $pshome to the ForEach-Object cmdlet, where Get-AuthenticodeSignature is called for each file.

    The results of the Get-AuthenticodeSignature command are sent to a Where-Object command that selects only the signature objects with a status of “Valid”.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113307
    about_Signing
    about_execution_policies
    Set-AuthenticodeSignature
    Get-ExecutionPolicy
    Set-ExecutionPolicy

ChildItem, cmdlet, Get

Get-ChildItem

NAME
    Get-ChildItem

SYNOPSIS
    Gets the items and child items in one or more specified locations.

SYNTAX
    Get-ChildItem [[-Path] <string[]>] [[-Filter] <string>] [-Exclude <string[]>] [-Force] [-Include <string[]>] [-Name] [-Recurse] [-UseTransaction] [<CommonParameters>]

    Get-ChildItem [-LiteralPath] <string[]> [[-Filter] <string>] [-Exclude <string[]>] [-Force] [-Include <string[]>] [-Name] [-Recurse] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Get-ChildItem cmdlet gets the items in one or more specified locations. If the item is a container, it gets the items inside the container, known as child items. You can use the Recurse parameter to get items in all child containers.

    A location can be a file system location, such as a directory, or a location exposed by another provider, such as a Registry hive or a Certificate store.

PARAMETERS
    -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?                    2
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Force [<SwitchParameter>]
        Allows the cmdlet to get items that cannot otherwise not be accessed by the user, such as hidden or system files. 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[]>
        Retrieves 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.

        The Include parameter is effective only when the command includes the Recurse parameter or the path leads to the contents of a directory, such as C:\Windows\*, where the wildcard character specifies the contents of the C:\Windows directory.

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

    -LiteralPath <string[]>
        Specifies a path to one or more locations. 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 [<SwitchParameter>]
        Retrieves only the names of the items in the locations. If you pipe the output of this command to another command, only the item names are sent.

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

    -Path <string[]>
        Specifies a path to one or more locations. Wildcards are permitted. The default location is the current directory (.).

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

    -Recurse [<SwitchParameter>]
        Gets the items in the specified locations and in all child items of the locations.

        Recurse works only when the path points to a container that has child items, such as C:\Windows or C:\Windows\*, and not when it points to items that do not have child items, such as C:\Windows\*.exe.

        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

    <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.String
        You can pipe a string that contains a path to Get-ChildItem.

OUTPUTS
    Object.
        The type of object that Get-ChildItem returns is determined by the provider with which it is used.

NOTES

        You can also refer to Get-ChildItem by its built-in Aliases, “ls”, “dir”, and “gci”. For more information, see about_aliases.

        Get-ChildItem does not get hidden items by default. To get hidden items, use -Force.

        The Get-ChildItem 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>Get-ChildItem

    Description
    ———–
    This command gets the child items in the current location. If the location is a file system directory, it gets the files and sub-directories in the current directory. If the item does not have child items, this command returns to the command prompt without displaying anything.

    The default display lists the mode (attributes), last write time, file size (length), and the name of the file. The valid values for mode are d (directory), a (archive), r (read-only), h (hidden), and s (system).

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

    C:\PS>Get-ChildItem . -Include *.txt -Recurse -Force

    Description
    ———–
    This command retrieves all of the .txt files in the current directory and its subdirectories. The dot (.) represents the current directory and the Include parameter specifies the file name extension. The Recurse parameter directs Windows PowerShell to retrieve objects recursively, and it indicates that the subject of the command is the specified directory and its contents. The force parameter adds hidden files to the display.

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

    C:\PS>Get-ChildItem c:\windows\logs\* -Include *.txt -Exclude A*

    Description
    ———–
    This command lists the .txt files in the Logs subdirectory, except for those whose names start with the letter A. It uses the wildcard character (*) to indicate the contents of the Logs subdirectory, not the directory container. Because the command does not include the Recurse parameter, Get-ChildItem does not include the content of directory automatically; you need to specify it.

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

    C:\PS>Get-ChildItem Registry::hklm\software

    Description
    ———–
    This command retrieves all of the Registry keys in the HKEY_LOCAL_MACHINE\SOFTWARE key in the Registry of the local computer.

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

    C:\PS>Get-ChildItem -Name

    Description
    ———–
    This command retrieves only the names of items in the current directory.

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

    C:\PS>Get-ChildItem cert:\. -Recurse -codesigningcert

    Description
    ———–
    This command gets all of the Certificates in the Certificate store that have code-signing authority.

    The command uses the Get-ChildItem cmdlet. The path specifies the Cert: drive exposed by the Windows PowerShell Certificate provider. The backslash (\) symbol specifies a subdirectory of the Certificate store and the dot (.) represents the current directory, which would be the root directory of the Certificate store. The Recurse parameter specifies a recursive search.

    The CodeSigningCertificate parameter is a dynamic parameter that gets only Certificates with code-signing authority. For more information, type “Get-Help Certificate“.

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

    C:\PS>Get-ChildItem * -Include *.exe

    Description
    ———–
    This command retrieves all of the items in the current directory with a “.exe” file name extension. The wildcard character (*) represents the contents of the current directory (not the container). When using the Include parameter without the Recurse parameter, the path must point to contents, not a container.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113308
    about_providers
    Get-Item
    Get-Alias
    Get-Location
    Get-Process

Alias, cmdlet, Get

Get-Alias

NAME
    Get-Alias

SYNOPSIS
    Gets the Aliases for the current session.

SYNTAX
    Get-Alias [[-Name] <string[]>] [-Exclude <string[]>] [-Scope <string>] [<CommonParameters>]

    Get-Alias [-Definition <string[]>] [-Exclude <string[]>] [-Scope <string>] [<CommonParameters>]

DESCRIPTION
    The Get-Alias cmdlet gets the Aliases (alternate names for commands and executable files) in the current session. This includes built-in Aliases, Aliases that you have set or imported, and Aliases that you have added to your Windows PowerShell profile.

    By default, Get-Alias takes an Alias and returns the command name. When you use the Definition parameter, Get-Alias takes a command name and returns its Aliases.

PARAMETERS
    -Definition <string[]>
        Gets the Aliases for the specified item. Enter the name of a cmdlet, Function, script, file, or executable file.

        This parameter is called Definition, because it searches for the item name in the Definition property of the Alias object.

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

    -Exclude <string[]>
        Omits the specified items. The value of this parameter qualifies the Name and Definition parameters. Enter a name, a definition, or a pattern, such as “s*”. Wildcards are permitted.

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

    -Name <string[]>
        Specifies the Aliases to retrieve. Wildcards are permitted. By default, Get-Alias retrieves all Aliases defined for the current session. The parameter name (“Name”) is optional. You can also pipe Alias names to Get-Alias.

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

    -Scope <string>
        Gets only the Aliases in the specified scope. 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

    <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.String
        You can pipe Alias names to Get-Alias.

OUTPUTS
    System.Management.Automation.AliasInfo
        Get-Alias returns an object that represents each Alias.

NOTES

        An Alias is an alternate name or nickname for a cmdlet, Function, or an executable file. To run the cmdlet, Function, or executable, you can use its full name or any Alias. For more information, see about_aliases.

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

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

    C:\PS>Get-Alias

    Description
    ———–
    This command gets all Aliases in the current session.

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

    C:\PS>Get-Alias -Name g*, s* -Exclude get-*

    Description
    ———–
    This command gets all Aliases that begin with “g” or “s”, except for Aliases that begin with “get-“.

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

    C:\PS>Get-Alias -definition Get-ChildItem

    Description
    ———–
    This command gets the Aliases for the Get-ChildItem cmdlet.

    By default, the Get-Alias cmdlet gets the item name when you know the Alias. The Definition parameter gets the Alias when you know the item name.

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

    C:\PS>Get-Alias | Where-Object {$_.Options -match “ReadOnly”}

    Description
    ———–
    This command retrieves all Aliases in which the value of the Options property is ReadOnly. This command provides a quick way to find the Aliases that are built into Windows PowerShell, because they have the ReadOnly option.

    Options is just one property of the AliasInfo objects that Get-Alias gets. To find all properties and methods of AliasInfo objects, type “Get-Alias | Get-Member“.

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

    C:\PS>Get-Alias -definition “*-pssession” -Exclude e* -Scope global

    Description
    ———–
    This example gets Aliases for commands that have names that end in “-pssession”, except for those that begin with “e”.

    The command uses the Scope parameter to apply the command in the global scope. This is useful in scripts when you want to get the Aliases in the session.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113306
    about_aliases
    Set-Alias
    New-Alias
    Export-Alias
    Import-Alias
    Alias Provider

Acl, cmdlet, Get

Get-Acl

NAME
    Get-Acl

SYNOPSIS
    Gets the security descriptor for a resource, such as a file or Registry key.

SYNTAX
    Get-Acl [[-Path] <string[]>] [-Audit] [-Exclude <string[]>] [-Filter <string>] [-Include <string[]>] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Get-Acl cmdlet gets objects that represent the security descriptor of a file or resource. The security descriptor contains the access control lists (ACLs) of the resource. The ACL specifies the permissions that users and user groups have to access the resource.

PARAMETERS
    -Audit [<SwitchParameter>]
        Gets the audit data for the security descriptor from the system access control list (SACL).

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        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

    -Include <string[]>
        Retrieves 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

    -Path <string[]>
        Specifies the path to a resource. Get-Acl gets the security descriptor of the resource indicated by the path. Wildcards are permitted. If you omit the Path parameter, Get-Acl gets the security descriptor of the current directory.

        The parameter name (“Path”) is optional.

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?     true (ByValue, 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

    <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.String
        You can pipe a string that contains a path to Get-Acl.

OUTPUTS
    System.Security.AccessControl
        Get-Acl returns an object that represents the ACLs that it gets. The object type depends upon the ACL type.

NOTES

        By default, Get-Acl displays the Windows PowerShell path to the resource (<provider>::<resource-Path>), the owner of the resource, and “Access”, a list (array) of the access control entries in the discretionary access control list (DACL) for the resource. The DACL list is controlled by the resource owner.

        When you format the result as a list, (“Get-Acl | Format-List“), in addition to the path, owner, and access list, Windows PowerShell displays the following fields:

        — Group: The security group of the owner.

        — Audit: A list (array) of entries in the system access control list (SACL). The SACL specifies the types of access attempts for which Windows generates audit records.

        — Sddl: The security descriptor of the resource displayed in a single text string in Security Descriptor Definition Language format. Windows PowerShell uses the GetSddlForm method of security descriptors to retrieve this data.

        Because Get-Acl is supported by the file system and Registry providers, you can use Get-Acl to view the ACL of file system objects, such as files and directories, and Registry objects, such as Registry keys and entries.

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

    C:\PS>Get-Acl C:\windows

    Description
    ———–
    This command gets the security descriptor of the C:Windows directory.

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

    C:\PS>Get-Acl C:\Windows\k*.log | Format-List -property PSPath, Sddl

    Description
    ———–
    This command gets the Windows PowerShell path and SDDL for all of the .log files in the C:\Windows directory whose names begin with “k.”

    The command uses Get-Acl to get objects representing the security descriptors of each log file. It uses a pipeline operator (|) to send the results to the Format-List cmdlet. The command uses the Property parameter of Format-List to display only the PsPath and SDDL properties of each security descriptor object.

    Lists are often used in Windows PowerShell, because long values appear truncated in tables.

    The SDDL values are valuable to system administrators, because they are simple text strings that contain all of the information in the security descriptor. As such, they are easy to pass and store, and they can be parsed when needed.

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

    C:\PS>Get-Acl c:/windows/k*.log -Audit | ForEach-Object { $_.Audit.Count }

    Description
    ———–
    This command gets the security descriptors of the .log files in the C:\Windows directory whose names begin with “k.” It uses the Audit parameter to retrieve the audit records from the SACL in the security descriptor. Then it uses the For-EachObject parameter to count the number of audit records associated with each file. The result is a list of numbers representing the number of audit records for each log file.

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

    C:\PS>Get-Acl -Path hklm:\system\currentcontrolset\control | Format-List

    Description
    ———–
    This command uses Get-Acl to get the security descriptor of the Control subkey (HKLM\SYSTEM\CurrentControlSet\Control) of the Registry.

    The Path parameter specifies the Control subkey. The pipeline operator (|) passes the security descriptor that Get-Acl retrieves to the Format-List command, which formats the properties of the security descriptor as a list so that they are easy to read.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113305
    Set-Acl

cmdlet, Format, Wide

Format-Wide

NAME
    Format-Wide

SYNOPSIS
    Formats objects as a wide table that displays only one property of each object.

SYNTAX
    Format-Wide [[-Property] <Object>] [-AutoSize] [-Column <int>] [-DisplayError] [-Expand <string>] [-Force] [-GroupBy <Object>] [-InputObject <psobject>] [-ShowError] [-View <string>] [<CommonParameters>]

DESCRIPTION
    The Format-Wide cmdlet formats objects as a wide table that displays only one property of each object. You can use the Property parameter to determine which property is displayed.

PARAMETERS
    -AutoSize [<SwitchParameter>]
        Adjusts the column size and number of columns based on the width of the data. By default, the column size and number are determined by the view. You cannot use the AutoSize and Column parameters in the same command.

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

    -Column <int>
        Specifies the number of columns in the display. You cannot use the AutoSize and Column parameters in the same command.

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

    -DisplayError [<SwitchParameter>]
        Displays errors at the command line.

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

    -Expand <string>
        Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.

        Valid values are:
        — EnumOnly: Displays the properties of the objects in the collection.
        — CoreOnly: Displays the properties of the collection object.
        — Both: Displays the properties of the collection object and the properties of objects in the collection.

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

    -Force [<SwitchParameter>]
        Overrides restrictions that prevent the command from succeeding, just so the changes do not compromise security. For example, Force will override the read-only attribute or create directories to complete a file path, but it will not attempt to change file permissions.

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

    -GroupBy <Object>
        Formats the output in groups based on a shared property or value. Enter an expression or a property of the output.

        The value of the GroupBy parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:

        — Name (or Label) <string>
        — Expression <string> or <script block>
        — FormatString <string>

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

    -InputObject <psobject>
        Specifies the objects to be formatted. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

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

    -Property <Object>
        Specifies the object properties that appear in the display and the order in which they appear. Wildcards are permitted.

        If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name (“Property”) is optional. You cannot use the Property and View parameters in the same command.

        The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:

        — Expression <string> or <script block>
        — FormatString <string>

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

    -ShowError [<SwitchParameter>]
        Sends errors through the pipeline.

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

    -View <string>
        Specifies the name of an alternate table format or “view.” You cannot use the Property and View parameters in the same 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.PSObject
        You can pipe any object to Format-Wide.

OUTPUTS
    Microsoft.PowerShell.Commands.Internal.Format
        Format-Wide returns format objects that represent the table.

NOTES

        You can also refer to Format-Wide by its built-in Alias, “fw”. For more information, see about_aliases.

        The GroupBy parameter assumes that the objects are sorted. Before using Format-Custom to group the objects, use Sort-Object to sort them.

        The -View parameter lets you specify an alternate format for the table. You can use the views defined in the *.format.PS1XML files in the Windows PowerShell directory or you can create your own views in new PS1XML files and use the Update-FormatData cmdlet to include them in Windows PowerShell.

        The alternate view for the View parameter must use table format; if it does not, the command fails. If the alternate view is a list, use Format-List. If the alternate view is neither a list nor a table, use Format-Custom.

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

    C:\PS>Get-ChildItem | Format-Wide -Column 3

    Description
    ———–
    This command displays the names of files in the current directory in three columns across the screen. The Get-ChildItem cmdlet gets objects representing each file in the directory. The pipeline operator (|) passes the file objects through the pipeline to Format-Wide, which formats them for output. The Column parameter specifies the number of columns.

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

    C:\PS>Get-ChildItem HKCU:\software\microsoft | Format-Wide -Property pschildname -AutoSize

    Description
    ———–
    This command displays the names of Registry keys in the HKEY_CURRENT_USER\Software\Microsoft key. The Get-ChildItem cmdlet gets objects representing the keys. The path is specified as “HKCU:”, one of the drives exposed by the Windows PowerShell Registry provider, followed by the key path. The pipeline operator (|) passes the Registry key objects through the pipeline to Format-Wide, which formats them for output. The Property parameter specifies the name of the property, and the AutoSize parameter adjusts the columns for readability.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113304

cmdlet, Format, Table

Format-Table

NAME
    Format-Table

SYNOPSIS
    Formats the output as a table.

SYNTAX
    Format-Table [[-Property] <Object[]>] [-AutoSize] [-DisplayError] [-Expand <string>] [-Force] [-GroupBy <Object>] [-HideTableHeaders] [-InputObject <psobject>] [-ShowError] [-View <string>] [-Wrap] [<CommonParameters>]

DESCRIPTION
    The Format-Table cmdlet formats the output of a command as a table with the selected properties of the object in each column. The object type determines the default layout and properties that are displayed in each column, but you can use the Property parameter to select the properties that you want to see.

    You can also use a hash table to add calculated properties to an object before displaying it and to specify the column headings in the table. To add a calculated property, use the Property or GroupBy parameters.

PARAMETERS
    -AutoSize [<SwitchParameter>]
        Adjusts the column size and number of columns based on the width of the data. By default, the column size and number are determined by the view.

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

    -DisplayError [<SwitchParameter>]
        Displays errors at the command line.

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

    -Expand <string>
        Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.

        Valid values are:
        — EnumOnly: Displays the properties of the objects in the collection.
        — CoreOnly: Displays the properties of the collection object.
        — Both: Displays the properties of the collection object and the properties of objects in the collection.

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

    -Force [<SwitchParameter>]
        Directs the cmdlet to display all of the error information. Use with the DisplayError or ShowError parameters. By default, when an error object is written to the error or display streams, only some of the error information is displayed.

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

    -GroupBy <Object>
        Arranges sorted output in separate tables based on a property value. For example, you can use GroupBy to list services in separate tables based on their status.

        Enter an expression or a property of the output. The output must be sorted before you send it to Format-Table.

        The value of the GroupBy parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:

        — Name (or Label) <string>
        — Expression <string> or <script block>
        — FormatString <string>

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

    -HideTableHeaders [<SwitchParameter>]
        Omits the column headings from the table.

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

    -InputObject <psobject>
        Specifies the objects to be formatted. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

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

    -Property <Object[]>
        Specifies the object properties that appear in the display and the order in which they appear. Type one or more property names (separated by commas), or use a hash table to display a calculated property. Wildcards are permitted.

        If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name (“Property”) is optional. You cannot use the Property and View parameters in the same command.

        The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:

        — Name (or Label) <string>
        — Expression <string> or <script block>
        — FormatString <string>
        — Width <int32>
        — Alignment (value can be “Left”, “Center”, or “Right”)

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

    -ShowError [<SwitchParameter>]
        Sends errors through the pipeline.

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

    -View <string>
        Specifies the name of an alternate table format or “view.” You cannot use the Property and View parameters in the same command.

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

    -Wrap [<SwitchParameter>]
        Displays text that exceeds the column width on the next line. By default, text that exceeds the column width is truncated.

        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.PSObject
        You can pipe any object to Format-Table.

OUTPUTS
    Microsoft.PowerShell.Commands.Internal.Format
        Format-Table returns format objects that represent the table.

NOTES

        You can also refer to Format-Table by its built-in Alias, “FT”. For more information, see about_aliases.

        The GroupBy parameter assumes that the objects are sorted. Before using Format-Custom to group the objects, use Sort-Object to sort them.

        The View parameter lets you specify an alternate format for the table. You can use the views defined in the *.format.PS1XML files in the Windows PowerShell directory or you can create your own views in new PS1XML files and use the Update-FormatData cmdlet to include them in Windows PowerShell.

        The alternate view for the View parameter must use table format; if it does not, the command fails. If the alternate view is a list, use Format-List. If the alternate view is neither a list nor a table, use Format-Custom.

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

    C:\PS>Get-PSSnapin | Format-Table -auto

    Description
    ———–
    This command formats information about Windows PowerShell snap-ins in a table. By default, they are formatted in a list. The Get-PSSnapin cmdlets gets objects representing the snap-ins. The pipeline operator (|) passes the object to the Format-Table command. Format-Table formats the objects in a table. The Autosize parameter adjusts the column widths to minimize truncation.

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

    C:\PS>Get-Process | Sort-Object -Property basepriority | Format-Table -GroupBy basepriority -Wrap

    Description
    ———–
    This command displays the processes on the computer in groups with the same base priority.

    The Get-Process cmdlet gets objects representing each process on the computer. The pipeline operator (|) passes the object to the Sort-Object cmdlet, which sorts the objects in order of their base priority.

    Another pipeline operator passes the results to the Format-Table command. The GroupBy parameter arranges the data about the processes into groups based on the value of their BasePriority property. The Wrap parameter ensures that data is not truncated.

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

    C:\PS>Get-Process | Sort-Object starttime | Format-Table -View starttime

    Description
    ———–
    This command displays information about the processes on the computer in group based on the start date of the process. It uses the Get-Process cmdlet to get objects representing the processes on the computer. The pipeline operator (|) sends the output of Get-Process to the Sort-Object cmdlet, which sorts it based on the StartTime property. Another pipeline operator sends the sorted results to Format-Table.

    The View parameter is used to select the StartTime view that is defined in the DotNetTypes.format.ps1xml formatting file for System.Diagnostics.Process objects, such as those returned by Get-Process. This view converts the StartTime of the process to a short date and then groups the processes by start date.

    The DotNetTypes.format.ps1xml formatting file also contains a Priority view for processes, and you can create your own format.ps1xml files with customized views.

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

    C:\PS>Get-Service | Format-Table -Property Name, DependentServices

    Description
    ———–
    This command displays all of the services on the computer in a table with two columns, Name and DependentServices. The command uses the Get-Service cmdlet to get all of the services on the computer. The pipeline operator (|) sends the results to the Format-Table cmdlet, which formats the output in a table. The Property parameter specifies the properties that appear in the table as columns. The name of the Property parameter is optional, so you can omit it (“Format-Table name, dependentservices”).

    Property and DependentServices are just two of the properties of service objects. To view all of the properties, type “Get-Service | Get-Member“.

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

    C:\PS>Get-Process notepad | Format-Table ProcessName, `
    @{Label=”TotalRunningTime”; Expression={(Get-Date) – $_.StartTime}}

    Description
    ———–
    This command shows how to use a calculated property in a table. The command displays a table with the process name and total running time of all Notepad processes on the local computer. The total running time is calculated by subtracting the start time of each process from the current time.

    The command uses the Get-Process cmdlet to get all processes named “Notepad” on the local computer. The pipeline operator (|) sends the results to Format-Table, which displays a table with two columns: ProcessName, a standard property of processes, and TotalRunningTime, a calculated property.

    The TotalRunningTime property is specified by a hash table with two keys, Label and Expression. The name of the property is assigned to the Label key. The calculation is assigned to the Expression key. The expression gets the StartTime property of each process object and subtracts it from the result of a Get-Date command, which gets the current date (and time).

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

    C:\PS>$processes = Get-WmiObject -ComputerName Server01 win32_process -filter “name=’notepad.exe'”

    C:\PS> $processes | Format-Table ProcessName, @{ Label = “Total Running Time”; `
    Expression={(Get-Date) – $_.ConvertToDateTime($_.CreationDate)}}

    Description
    ———–
    These commands are similar to the previous command, except that these commands use the Get-WmiObject cmdlet and the Win32_Process class to display information about Notepad processes on a remote computer.

    The first command uses the Get-WmiObject cmdlet to get instances of the Windows Management Instrumentation (WMI) Win32_Process class that describes all of the processes on the Server01 computer that are named Notepad.exe. The command stores the process information in the $processes Variable.

    The second command uses a pipeline operator (|) to send the process information in the $processes Variable to the Format-Table cmdlet, which displays the ProcessName of each process along with a new calculated property.

    The command assigns the name of the new calculated property, Total Running Time, to the Label key. The script block that is assigned to the Expression key calculates how long the process has been running by subtracting the creation date of the process from the current date. The Get-Date cmdlet gets the current date. The ConvertToDateTime method converts the CreationDate property of the Win32_Process object from a WMI CIM_DATETIME object to a Microsoft .NET Framework DateTime object that can be compared with the output of Get-Date. Then, the converted creation date is subtracted from the current date. The result is the value of Total Running Time.

    The backtick characters (`) are line continuation characters.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113303
    Format-List
    Format-Wide
    Format-Custom

cmdlet, Format, List

Format-List

NAME
    Format-List

SYNOPSIS
    Formats the output as a list of properties in which each property appears on a new line.

SYNTAX
    Format-List [[-Property] <Object[]>] [-DisplayError] [-Expand <string>] [-Force] [-GroupBy <Object>] [-InputObject <psobject>] [-ShowError] [-View <string>] [<CommonParameters>]

DESCRIPTION
    The Format-List cmdlet formats the output of a command as a list of properties in which each property is displayed on a separate line. You can use Format-List to format and display all or selected properties of an object as a list (Format-List *).

    Because more space is available for each item in a list than in a table, Windows PowerShell displays more properties of the object in the list, and the property values are less likely to be truncated.

PARAMETERS
    -DisplayError [<SwitchParameter>]
        Displays errors at the command line.

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

    -Expand <string>
        Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.

        Valid values are:
        — EnumOnly: Displays the properties of the objects in the collection.
        — CoreOnly: Displays the properties of the collection object.
        — Both: Displays the properties of the collection object and the properties of objects in the collection.

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

    -Force [<SwitchParameter>]
        Directs the cmdlet to display all of the error information. Use with the DisplayError or ShowError parameters. By default, when an error object is written to the error or display streams, only some of the error information is displayed.

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

    -GroupBy <Object>
        Formats the output in groups based on a shared property or value. Enter an expression or a property of the output.

        The value of the GroupBy parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:

        — Name (or Label) <string>
        — Expression <string> or <script block>
        — FormatString <string>

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

    -InputObject <psobject>
        Specifies the objects to be formatted. Enter a Variable that contains the objects or type a command or expression that gets the objects.

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

    -Property <Object[]>
        Specifies the object properties that appear in the display and the order in which they appear. Wildcards are permitted.

        If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name (“Property”) is optional. You cannot use the Property and View parameters in the same command.

        The value of the Property parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:

        — Name (or Label) <string>
        — Expression <string> or <script block>
        — FormatString <string>

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

    -ShowError [<SwitchParameter>]
        Sends errors through the pipeline.

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

    -View <string>
        Specifies the name of an alternate list format or “view.” You cannot use the Property and View parameters in the same 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.PSObject
        You can pipe any object to Format-List.

OUTPUTS
    Microsoft.PowerShell.Commands.Internal.Format
        Format-List returns the format objects that represent the list.

NOTES

        You can also refer to Format-List by its built-in Alias, “FL”. For more information, see about_aliases.

        The format cmdlets, such as Format-List, arrange the data to be displayed but do not display it. The data is displayed by the output features of Windows PowerShell and by the cmdlets that contain the Out verb (the Out cmdlets), such as Out-Host, Out-File, and Out-Printer.

        If you do not use a format cmdlet, Windows PowerShell applies that default format for each object that it displays.

        The GroupBy parameter assumes that the objects are sorted. Before using Format-Custom to group the objects, use Sort-Object to sort them.

        The View parameter lets you specify an alternate format for the table. You can use the views defined in the *.format.PS1XML files in the Windows PowerShell directory, or you can create your own views in new PS1XML files and use the Update-FormatData cmdlet to include them in Windows PowerShell.

        The alternate view for the View parameter must use the list format; if not, the command fails. If the alternate view is a table, use Format-Table. If the alternate view is neither a list nor a table, use Format-Custom.

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

    C:\PS>Get-Service | Format-List

    Description
    ———–
    This command formats information about services on the computer as a list. By default, the services are formatted as a table. The Get-Service cmdlet gets objects representing the services on the computer. The pipeline operator (|) passes the results through the pipeline to Format-List. Then, the Format-List command formats the service information in a list and sends it to the default output cmdlet for display.

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

    C:\PS>$a = Get-ChildItem $pshome\*.ps1xml

    Description
    ———–
    These commands display information about the PS1XML files in the Windows PowerShell directory as a list. The first command gets the objects representing the files and stores them in the $a Variable. The second command uses Format-List to format information about objects stored in $a. This command uses the InputObject parameter to pass the Variable to Format-List, which then sends the formatted output to the default output cmdlet for display.

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

    C:\PS>Get-Process | Format-List -Property name, basepriority, priorityclass

    Description
    ———–
    This command displays the name, base priority, and priority class of each process on the computer. It uses the Get-Process cmdlet to get an object representing each process. The pipeline operator (|) passes the process objects through the pipeline to Format-List. Format-List formats the processes as a list of the specified properties. The “Property” parameter name is optional, so you can omit it.

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

    C:\PS>Get-Process winlogon | Format-List -Property *

    Description
    ———–
    This command displays all of the properties of the Winlogon process. It uses the Get-Process cmdlet to get an object representing the Winlogon process. The pipeline operator (|) passes the Winlogon process object through the pipeline to Format-List. The command uses the Property parameter to specify the properties and the * to indicate all properties. Because the name of the Property parameter is optional, you can omit it and type the command as: “Format-List *”. Format-List automatically sends the results to the default output cmdlet for display.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113302

cmdlet, Custom, Format

Format-Custom

NAME
    Format-Custom

SYNOPSIS
    Uses a customized view to format the output.

SYNTAX
    Format-Custom [[-Property] <Object[]>] [-Depth <int>] [-DisplayError] [-Expand <string>] [-Force] [-GroupBy <Object>] [-InputObject <psobject>] [-ShowError] [-View <string>] [<CommonParameters>]

DESCRIPTION
    The Format-Custom cmdlet formats the output of a command as defined in an alternate view. Format-Custom is designed to display views that are not just tables or just lists. You can use the views defined in the *format.PS1XML files in the Windows PowerShell directory, or you can create your own views in new PS1XML files and use the Update-FormatData cmdlet to add them to Windows PowerShell.

PARAMETERS
    -Depth <int>
        Specifies the number of columns in the display.

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

    -DisplayError [<SwitchParameter>]
        Displays errors at the command line.

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

    -Expand <string>
        Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly.

        Valid values are:
        — EnumOnly: Displays the properties of the objects in the collection.
        — CoreOnly: Displays the properties of the collection object.
        — Both: Displays the properties of the collection object and the properties of objects in the collection.

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

    -Force [<SwitchParameter>]
        Directs the cmdlet to display all of the error information. Use with the DisplayError or ShowError parameters. By default, when an error object is written to the error or display streams, only some of the error information is displayed.

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

    -GroupBy <Object>
        Formats the output in groups based on a shared property or value. Enter an expression or a property of the output.

        The value of the GroupBy parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are:

        — Name (or Label) <string>
        — Expression <string> or <script block>
        — FormatString <string>

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

    -InputObject <psobject>
        Specifies the objects to be formatted. Enter a Variable that contains the objects or type a command or expression that gets the objects.

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

    -Property <Object[]>
        Specifies the object properties that appear in the display and the order in which they appear. Wildcards are permitted.

        If you omit this parameter, the properties that appear in the display depend on the object being displayed. The parameter name (“Property”) is optional. You cannot use the Property and View parameters in the same command.

        The value of the Property parameter can be a new calculated property. To create a calculated property, use a hash table. Valid keys are:

        — Expression <string> or <script block>
        — Depth <int32>

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

    -ShowError [<SwitchParameter>]
        Sends errors through the pipeline.

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

    -View <string>
        Specifies the name of an alternate format or “view.” If you omit this parameter, Format-Custom uses a default custom view. You cannot use the Property and View parameters in the same 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.PSObject
        You can pipe any object to Format-Custom

OUTPUTS
    Microsoft.PowerShell.Commands.Internal.Format
        Format-Custom returns the format objects that represent the display.

NOTES

        Format-Custom is designed to display views that are not just tables or just lists. To display an alternate table view, use Format-Table. To display an alternate list view, use Format-List.

        You can also refer to Format-Custom by its built-in Alias, “fc”. For more information, see about_aliases.

        The GroupBy parameter assumes that the objects are sorted. Before using Format-Custom to group the objects, use Sort-Object to sort them.

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

    C:\PS>Get-Command Start-Transcript | Format-Custom -View MyView

    Description
    ———–
    This command formats information about the Start-Transcript cmdlet in the format defined by the MyView view, a custom view created by the user. To run this command successfully, you must first create a new PS1XML file, define the MyView view, and then use the Update-FormatData command to add the PS1XML file to Windows PowerShell.

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

    C:\PS>Get-Process Winlogon | Format-Custom

    Description
    ———–
    This command formats information about the Winlogon process in an alternate customized view. Because the command does not use the View parameter, Format-Custom uses a default custom view to format the data.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113301

cmdlet, ForEach, Object

ForEach-Object

NAME
    ForEach-Object

SYNOPSIS
    Performs an operation against each of a set of input objects.

SYNTAX
    ForEach-Object [-Process] <ScriptBlock[]> [-Begin <scriptblock>] [-End <scriptblock>] [-InputObject <psobject>] [<CommonParameters>]

DESCRIPTION
    The ForEach-Object cmdlet performs an operation on each of a set of input objects. The input objects can be piped to the cmdlet or specified by using the InputObject parameter.

    The operation to perform is described within a script block that is provided to the cmdlet as the value of the Process parameter. The script block can contain any Windows PowerShell script.

    Within the script block, the current input object is represented by the $_ Variable.
    In addition to using the script block that describes the operations to be carried out on each input object, you can provide two additional script blocks. One, specified as the value of the Begin parameter, runs before the first input object is processed. The other, specified as the value of the End parameter, runs after the last input object is processed.

    The results of the evaluation of all the script blocks, including the ones specified with Begin and End, are passed down the pipeline.

PARAMETERS
    -Begin <scriptblock>
        Specifies a script block to run before processing any input objects.

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

    -End <scriptblock>
        Specifies a script block to run after processing all input objects.

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

    -InputObject <psobject>
        Accepts an object that the script block specified in the process parameter will act upon. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

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

    -Process <ScriptBlock[]>
        Specifies the script block that is applied to each incoming object.

        Required?                    true
        Position?                    1
        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.PSObject
        You can pipe any object to ForEach-Object.

OUTPUTS
    System.Management.Automation.PSObject
        The objects that ForEach-Object returns are determined by the input.

NOTES

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

    C:\PS>30000,56798,12432 | ForEach-Object -Process {$_/1024}

    Description
    ———–
    This command accepts an array of integers, divides each one of them by 1024, and displays the results.

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

    C:\PS>Get-ChildItem C:\ | ForEach-Object -Process { $_.length / 1024 }

    Description
    ———–
    This command retrieves the files and directories in the root of the C: drive, and it returns and displays the size of each of them. The zeros represent directories in which no file size was available.

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

    C:\PS>$events = Get-Eventlog -logname system -newest 1000

    C:\PS> $events | ForEach-Object -Begin {Get-Date} -Process {Out-File -filepath events.txt -append -InputObject $_.message} -End {Get-Date}

    Description
    ———–
    This command retrieves the 1000 most recent events from the system log and stores them in the $events Variable. It then pipes the events to the ForEach-Object cmdlet. The Begin parameter displays the current date and time. Next, the Process parameter uses the Out-File cmdlet to create a text file named events.txt and stores the message property of each of the events in that file. Last, the End parameter is used to display the date and time after all of the processing has completed.

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

    C:\PS>Get-Itemproperty -path hkcu:\Network\* | ForEach-Object {Set-Itemproperty -path $_.pspath -name RemotePath -value $_.RemotePath.ToUpper();}

    Description
    ———–
    This command changes the value of the RemotePath Registry entry in all of the subkeys under the HKCU:\Network key to uppercase text. You can use this format to change the form or content of a Registry entry value.

    Each subkey in the Network key represents a mapped network drive that will reconnect at logon. The RemotePath entry contains the UNC path of the connected drive. For example, if you map the E: drive to \\Server\Share, there will be an E subkey of HKCU:\Network and the value of the RemotePath Registry entry in the E subkey will be \\Server\Share.

    The command uses the Get-ItemProperty cmdlet to get all of the subkeys of the Network key and the Set-ItemProperty cmdlet to change the value of the RemotePath Registry entry in each key. In the Set-ItemProperty command, the path is the value of the PSPath property of the Registry key. (This is a property of the Microsoft .NET Framework object that represents the Registry key; it is not a Registry entry.) The command uses the ToUpper() method of the RemotePath value, which is a string (REG_SZ).

    Because Set-ItemProperty is changing the property of each key, the ForEach-Object cmdlet is required to access the property.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113300

cmdlet, Export, PSSession

Export-PSSession

NAME
    Export-PSSession

SYNOPSIS
    Imports commands from another session and saves them in a Windows PowerShell module.

SYNTAX
    Export-PSSession [-Session] <PSSession> [-OutputModule] <string> [[-CommandName] <string[]>] [[-FormatTypeName] <string[]>] [-AllowClobber] [-ArgumentList <Object[]>] [-CommandType {Alias | Function | Filter | Cmdlet | ExternalScript | Application | Script | All}] [-Encoding <string>] [-Force] [-Module <string[]>] [<CommonParameters>]

DESCRIPTION
    The Export-PSSession cmdlet gets cmdlets, Functions, Aliases, and other command types from another PSSession on a local or remote computer and saves them in a Windows PowerShell module. To add the commands from the module to the current session, use the Import-Module cmdlet.

    Unlike Import-PSSession, which imports commands from another PSSession into the current session, Export-PSSession saves the commands in a module. The commands are not imported into the current session.

    To export commands, first use the New-PSSession cmdlet to create a PSSession that has the commands that you want to export. Then use the Export-PSSession cmdlet to export the commands. By default, Export-PSSession exports all commands, except for commands that exist in the current session, but you can use the CommandName parameters to specify the commands to export.

    The Export-PSSession cmdlet uses the implicit remoting feature of Windows PowerShell. When you import commands into the current session, they run implicitly in the original session or in a similar session on the originating computer.

PARAMETERS
    -AllowClobber [<SwitchParameter>]
        Exports the specified commands, even if they have the same names as commands in the current session.

        If you import a command with the same name as a command in the current session, the imported command hides or replaces the original commands. For more information, see about_command_precedence.

        Export-PSSession does not import commands that have the same names as commands in the current session. The default behavior is designed to prevent command name conflicts.

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

    -ArgumentList <Object[]>
        Exports the variant of the command that results from using the specified arguments (parameter values).

        For example, to export the variant of the Get-Item command in the Certificate (Cert:) drive in the PSSession in $s, type “Export-PSSession -Session $s -command Get-Item -ArgumentList cert:”.

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

    -CommandName <string[]>
        Exports only the commands with the specified names or name patterns. Wildcards are permitted. Use “CommandName” or its Alias, “Name”.

        By default, Export-PSSession exports all commands from the PSSession except for commands that have the same names as commands in the current session. This prevents imported commands from hiding or replacing commands in the current session. To export all commands, even those that hide or replace other commands, use the AllowClobber parameter.

        If you use the CommandName parameter, the formatting files for the commands are not exported unless you use the FormatTypeName parameter. Similarly, if you use the FormatTypeName parameter, no commands are exported unless you use the CommandName parameter.

        Required?                    false
        Position?                    3
        Default value                All commands in the session.
        Accept pipeline input?     false
        Accept wildcard characters? true

    -CommandType <CommandTypes>
        Exports only the specified types of command objects. Use “CommandType” or its Alias, “Type”.

        Valid values are:
        — Alias: All Windows PowerShell Aliases in the current session.
        — All: All command types. It is the equivalent of “Get-Command *”.
        — Application: All files other than Windows PowerShell files in paths listed in the Path Environment Variable ($env:path), including .txt, .exe, and .dll files.
        — Cmdlet: The cmdlets in the current session. “Cmdlet” is the default.
        — ExternalScript: All .ps1 files in the paths listed in the Path Environment Variable ($env:path).
        — Filter and Function: All Windows PowerShell Functions.
        — Script: Script blocks in the current session.

        Required?                    false
        Position?                    named
        Default value                All commands in the session.
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Encoding <string>
        Specifies the encoding for the output files. Valid values are “Unicode”, “UTF7”, “UTF8”, “ASCII”, “UTF32”, “BigEndianUnicode”, “Default”, and “OEM”. The default is “UTF-8”.

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

    -Force [<SwitchParameter>]
        Overwrites one or more existing output files, even if the file has the read-only attribute.

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

    -FormatTypeName <string[]>
        Exports formatting instructions only for the specified Microsoft .NET Framework types. Enter the type names. By default, Export-PSSession exports formatting instructions for all .NET Framework types that are not in the System.Management.Automation namespace.

        The value of this parameter must be the name of a type that is returned by a Get-FormatData command in the session from which the commands are being imported. To get all of the formatting data in the remote session, type *.

        If you use the FormatTypeName parameter, no commands are exported unless you use the CommandName parameter.
        Similarly, if you use the CommandName parameter, the formatting files for the commands are not exported unless you use the FormatTypeName parameter.

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

    -Module <string[]>
        Exports only the commands in the specified Windows PowerShell snap-ins and modules. Enter the snap-in and module names. Wildcards are not permitted.

        For more information, see about_PSSnapins and Import-Module.

        Required?                    false
        Position?                    named
        Default value                All commands in the session.
        Accept pipeline input?     false
        Accept wildcard characters? false

    -OutputModule <string>
        Specifies a path (optional) and name for the module that Export-PSSession creates. The default path is $home\Documents\WindowsPowerShell\Modules. This parameter is required.

        If the module subdirectory or any of the files that Export-PSSession creates already exist, the command fails. To overwrite existing files, use the Force parameter.

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

    -Session <PSSession>
        Specifies the PSSession from which the commands are exported. Enter a Variable that contains a session object or a command that gets a session object, such as a Get-PSSession command. This parameter is required.

        Required?                    true
        Position?                    1
        Default value                None
        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
    None
        You cannot pipe objects to Export-PSSession.

OUTPUTS
    System.IO.FileInfo
        Export-PSSession returns a list of files that comprise the module that it created.

NOTES

        Export-PSSession relies on the Windows PowerShell remoting infrastructure. To use this cmdlet, the computer must be configured for remoting. For more information, see about_remote_requirements.

        You cannot use Export-PSSession to export a Windows PowerShell provider.

        Exported commands run implicitly in the PSSession from which they were exported. However, the details of running the commands remotely are handled entirely by Windows PowerShell. You can run the exported commands just as you would run local commands.

        Export-Module captures and saves information about the PSSession in the module that it exports. If the PSSession from which the commands were exported is closed when you import the module, and there are no active PSSessions to the same computer, the commands in the module attempt to re-create the PSSession. If attempts to re-create the PSSession fail, the exported commands will not run.

        The session information that Export-Module captures and saves in the module does not include session options, such as those that you specify in the $PSSessionOption automatic Variable or by using the SessionOption parameters of the New-PSSession, Enter-PSSession, or Invoke-Command cmdlet. If the original PSSession is closed when you import the module, the module will use another PSSession to the same computer, if one is available. To enable the imported commands to run in a correctly configured session, create a PSSession with the options that you want before you import the module.

        To find the commands to export, Export-PSSession uses the Invoke-Command cmdlet to run a Get-Command command in the PSSession. To get and save formatting data for the commands, it uses the Get-FormatData and Export-FormatData cmdlets. You might see error messages from Invoke-Command, Get-Command, Get-FormatData, and Export-FormatData when you run an Export-PSSession command. Also, Export-PSSession cannot export commands from a session that does not include the Get-Command, Get-FormatData, Select-Object, and Get-Help cmdlets.

        Export-PSSession uses the Write-Progress cmdlet to display the progress of the command. You might see the progress bar while the command is running.

        Exported commands have the same limitations as other remote commands, including the inability to start a program with a user interface, such as Notepad.

        Because Windows PowerShell profiles are not run in PSSessions, the commands that a profile adds to a session are not available to Export-PSSession. To export commands from a profile, use an Invoke-Command command to run the profile in the PSSession manually before exporting commands.

        The module that Export-PSSession creates might include a formatting file, even if the command does not import formatting data. If the command does not import formatting data, any formatting files that are created will not contain formatting data.

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

    C:\PS>$s = New-PSSession -computerName Server01

    C:\PS> Export-PSSession -Session $s -OutputModule Server01

    Description
    ———–
    The commands in this example export all commands from a PSSession on the Server01 computer to the Server01 module on the local computer except for commands that have the same names as commands in the current session. It also exports the formatting data for the commands.

    The first command creates a PSSession on the Server01 computer. The second command exports the commands and formatting data from the session into the Server01 module.

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

    C:\PS>$s = New-PSSession -ConnectionUri http://exchange.microsoft.com/mailbox -credential exchangeadmin01@hotmail.com -authentication negotiate

    C:\PS> Export-PSSession -Session $r -Module exch* -CommandName get-*, set-* -FormatTypeName * -OutputModule $pshome\Modules\Exchange -Encoding ASCII

    Description
    ———–
    These commands export the Get and Set commands from a Microsoft Exchange Server snap-in on a remote computer to an Exchange module in the $pshome\Modules directory on the local computer.

    Placing the module in the $pshome\Module directory makes it accessible to all users of the computer.

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

    C:\PS>$s = New-PSSession -computerName Server01 -credential Server01\User01

    C:\PS> Export-PSSession -Session $s -OutputModule TestCmdlets -type cmdlet -CommandName *test* -FormatTypeName *

    C:\PS> Remove-PSSession $s

    C:\PS> Import-Module TestCmdlets

    C:\PS> Get-Help test*

    C:\PS> test-files

    Description
    ———–
    These commands export cmdlets from a PSSession on a remote computer and save them in a module on the local computer. Then, the commands add the cmdlets from the module to the current session so that they can be used.

    The first command creates a PSSession on the Server01 computer and saves it in the $s Variable.

    The second command exports the cmdlets whose names begin with “Test” from the PSSession in $s to the TestCmdlets module on the local computer.

    The third command uses the Remove-PSSession cmdlet to delete the PSSession in $s from the current session. This command shows that the PSSession need not be active to use the commands that were imported from it.

    The fourth command, which can be run in any session at any time, uses the Import-Module cmdlet to add the cmdlets in the TestCmdlets module to the current session.

    The fifth command uses the Get-Help cmdlet to get help for cmdlets whose names begin with “Test.” After the commands in a module are added to the current session, you can use the Get-Help and Get-Command cmdlets to learn about the imported commands, just as you would use them for any command in the session.

    The sixth command uses the Test-Files cmdlet, which was exported from the Server01 computer and added to the session.

    Although it is not evident, the Test-Files command actually runs in a remote session on the computer from which the command was imported. Windows PowerShell creates a session from information that is stored in the module.

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

    C:\PS>Export-PSSession -Session $s -AllowClobber -OutputModule AllCommands

    Description
    ———–
    This command exports all commands and all formatting data from the PSSession in the $s Variable into the current session. The command uses the AllowClobber parameter to include commands with the same names as commands in the current session.

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

    C:\PS>$options = New-PSSessionOption -NoMachineProfile

    C:\PS> $s = New-PSSession -computername Server01 -Sessionoption $options

    C:\PS> Export-PSSession -Session $s -OutputModule Server01

    C:\PS> Remove-PSSession $s

    C:\PS> New-PSSession -computername Server01 -Sessionoption $options

    C:\PS> Import-Module Server01

    Description
    ———–
    This example shows how to run the exported commands in a session with particular options when the PSSession from which the commands were exported is closed.

    When you use Export-PSSession, it saves information about the original PSSession in the module that it creates. When you import the module, if the original remote session is closed, the module will use any open remote session that connects to originating computer.

    If the current session does not include a remote session to the originating computer, the commands in the module will re-establish a session to that computer. However, Export-PSSession does not save special options, such as those set by using the SessionOption parameter of New-PSSession, in the module.

    Therefore, if you want to run the exported commands in a remote session with particular options, you need to create a remote session with the options that you want before you import the module.

    The first command uses the New-PSSessionOption cmdlet to create a PSSessionOption object, and it saves the object in the $options Variable.

    The second command creates a PSSession that includes the specified options. The command uses the New-PSSession cmdlet to create a PSSession on the Server01 computer. It uses the SessionOption parameter to submit the option object in $options.

    The third command uses the Export-PSSession cmdlet to export commands from the PSSession in $s to the Server01 module.

    The fourth command uses the Remove-PSSession cmdlet to delete the PSSession in the $s Variable.

    The fifth command uses the New-PSSession cmdlet to create a new PSSession that connects to the Server01 computer. This PSSession also uses the session options in the $options Variable.

    The sixth command uses the Import-Module cmdlet to import the commands from the Server01 module. The commands in the module run in the PSSession on the Server01 computer.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=135213
    about_command_precedence
    Import-PSSession
    New-PSSession
    Import-Module
    Invoke-Command
    about_pssessions