Category Archives: HelpFile

about_Comment_Based_Help

February 26, 2014 Adam

SHORT DESCRIPTION
Describes how to write comment-based Help topics for Functions and scripts.

LONG DESCRIPTION
You can write comment-based Help topics for Functions and scripts by using
special Help comment keywords.

    The Get-Help cmdlet displays comment-based Help in the same format in which
    it displays the cmdlet Help topics that are generated from XML files. Users
    can use all of the parameters of Get-Help, such as Detailed, Full, Example,
    and Online, to display Function and script Help.

You can also write XML-based Help files for scripts and Functions by using
Help comment keywords, and you can redirect users to a different Help file.

    This topic explains how to write Help topics for Functions and scripts. For
    information about how to display Help topics for Functions and scripts, see
    Get-Help.

SYNTAX FOR COMMENT-BASED HELP
The syntax for comment-based Help is as follows:

# .< help keyword>
# <help content>

-or –

        <#
            .< help keyword>
            < help content>
        #>

    Comment-based Help is written as a series of comments. You can type a
    comment symbol (#) before each line of comments, or you can use the “<#” and “#>”
    symbols to create a comment block. All the lines within the comment block are
    interpreted as comments.

    All of the lines in a comment-based Help topic must be contiguous. If a
    comment-based Help topic follows a comment that is not part of the Help
    topic, there must be at least one blank line between the last non-Help
    comment line and the beginning of the comment-based Help.

    Keywords define each section of comment-based Help. Each comment-based Help
    keyword is preceded by a dot (.). The keywords can appear in any order. The
    keyword names are not case-sensitive.

For example, the Description keyword precedes a description of a Function or
script.

        <#
        .Description
            Get-Function displays the name and syntax of all Functions in the session.
        #>

    The comment block must contain at least one keyword. Some of the keywords,
    such as EXAMPLE, can appear many times in the same comment block. The Help
    content for each keyword begins on the line after the keyword and can span
    multiple lines.

SYNTAX FOR COMMENT-BASED HELP IN FunctionS

Comment-based Help for a Function can appear in one of three locations:

— At the beginning of the Function body.

— At the end of the Function body.

        — Before the Function keyword. There cannot be more than one blank
         line between the last line of the Function Help and the Function
         keyword.

For example:

        Function MyFunction
        {
            <#
            .< help keyword>
            < help content>
            #>

<function commands>
}

-or –

        Function MyFunction
        {
            <function commands>

            <#
            .< help keyword>
            < help content>
            #>
        }

-or –

        <#
        .< help keyword>
        < help content>
        #>
        Function MyFunction { }

SYNTAX FOR COMMENT-BASED HELP IN SCRIPTS

Comment-based Help for a script can appear in one of the following two
locations in the script.

— At the beginning of the script file. Script Help can be preceded in the
script only by comments and blank lines.

    — If the first item in the script body (after the Help) is a Function
     declaration, there must be at least two blank lines between the end of the
     script Help and the Function declaration. Otherwise, the Help is
     interpreted as being Help for the Function, not Help for the script.

— At the end of the script file.

For example:

        <#
        .< help keyword>
        < help content>
        #>

Function MyFunction { }

-or-

Function MyFunction { }

        <#
        .< help keyword>
        < help content>
        #>

COMMENT-BASED HELP KEYWORDS
    The following are valid comment-based Help keywords. They are listed in the order in
    which they typically appear in a Help topic along with their intended use.
    These keywords can appear in any order in the comment-based Help, and they
    are not case-sensitive.

    .SYNOPSIS
        A brief description of the Function or script. This keyword can be used
        only once in each topic.

    .DESCRIPTION
        A detailed description of the Function or script. This keyword can be
        used only once in each topic.

    .PARAMETER <Parameter-Name>
        The description of a parameter. You can include a Parameter keyword for
        each parameter in the Function or script syntax.

        The Parameter keywords can appear in any order in the comment block, but
        the Function or script syntax determines the order in which the parameters
        (and their descriptions) appear in Help topic. To change the order,
        change the syntax.

        You can also specify a parameter description by placing a comment in the
        Function or script syntax immediately before the parameter Variable name.
        If you use both a syntax comment and a Parameter keyword, the description
        associated with the Parameter keyword is used, and the syntax comment is
        ignored.

    .EXAMPLE
        A sample command that uses the Function or script, optionally followed
        by sample output and a description. Repeat this keyword for each example.

    .INPUTS
        The Microsoft .NET Framework types of objects that can be piped to the
        Function or script. You can also include a description of the input
        objects.

    .OUTPUTS
        The .NET Framework type of the objects that the cmdlet returns. You can
        also include a description of the returned objects.

.NOTES
Additional information about the Function or script.

.LINK
The name of a related topic. Repeat this keyword for each related topic.

This content appears in the Related Links section of the Help topic.

        The Link keyword content can also include a Uniform Resource Identifier
        (URI) to an online version of the same Help topic. The online version
        opens when you use the Online parameter of Get-Help. The URI must begin
        with “http” or “https”.

    .COMPONENT
        The technology or feature that the Function or script uses, or to which
        it is related. This content appears when the Get-Help command includes
        the Component parameter of Get-Help.

    .ROLE
        The user role for the Help topic. This content appears when the Get-Help
        command includes the Role parameter of Get-Help.

    .FUNCTIONALITY
        The intended use of the Function. This content appears when the Get-Help
        command includes the Functionality parameter of Get-Help.

    .FORWARDHELPTARGETNAME <Command-Name>
        Redirects to the Help topic for the specified command. You can redirect
        users to any Help topic, including Help topics for a Function, script,
        cmdlet, or provider.

    .FORWARDHELPCATEGORY <Category>
        Specifies the Help category of the item in ForwardHelpTargetName.
        Valid values are Alias, Cmdlet, HelpFile, Function, Provider, General,
        FAQ, Glossary, ScriptCommand, ExternalScript, Filter, or All. Use this
        keyword to avoid conflicts when there are commands with the same name.

    .REMOTEHELPRUNSPACE <PSSession-variable>
        Specifies a session that contains the Help topic. Enter a Variable that
        contains a PSSession. This keyword is used by the Export-PSSession
        cmdlet to find the Help topics for the exported commands.

.EXTERNALHELP <XML Help File Path>
Specifies the path to an XML-based Help file for the script or Function.

        In Windows Vista and later versions of Windows, if the specified path
        to the XML file contains UI-culture-specific subdirectories, Get-Help
        searches the subdirectories recursively for an XML file with the name
        of the script or Function in accordance with the language fallback
        standards established for Windows Vista, just as it does for all
        XML-based Help topics.

        For more information about the cmdlet Help XML-based Help file format,
        see “How to Create Cmdlet Help” in the MSDN (Microsoft Developer Network)
        library at http://go.microsoft.com/fwlink/?LinkID=123415.

AUTOGENERATED CONTENT
The name, syntax, parameter list, parameter attribute table, common
parameters, and remarks are automatically generated by the Get-Help cmdlet.

        Name:
            The Name section of a Function Help topic is taken from the Function
            name in the Function syntax. The Name of a script Help topic is
            taken from the script file name. To change the name or its
            capitalization, change the Function syntax or the script file name.

        Syntax:
            The Syntax section of the Help topic is generated from the Function
            or script syntax. To add detail to the Help topic syntax, such as
            the .NET Framework type of a parameter, add the detail to the syntax.
            If you do not specify a parameter type, the “Object” type is
            inserted as the default value.

        Parameter List:
            The Parameter list in the Help topic is generated from the Function
            or script syntax and from the descriptions that you add by using the
            Parameters keyword. The Function parameters appear in the “Parameters”
            section of the Help topic in the same order that they appear in
            the Function or script syntax. The spelling and capitalization of
            parameter names is also taken from the syntax; it is not affected
            by the parameter name specified by the Parameter keyword.

        Common Parameters:
            The common parameters are added to the syntax and parameter list
            of the Help topic, even if they have no effect. For more information
            about the common parameters, see about_CommonParameters.

        Parameter Attribute Table:
            Get-Help generates the table of parameter attributes that appears
            when you use the Full or Parameter parameter of Get-Help. The value
            of the Required, Position, and Default value attributes is taken
            from the Function or script syntax.

        Remarks:
            The Remarks section of the Help topic is automatically generated
            from the Function or script name. You cannot change or affect its
            content.

EXAMPLES

Example 1: Comment-based Help for a Function

The following sample Function includes comment-based Help:

            Function Add-Extension
            {
                param ([string]$Name,[string]$Extension = “txt”)
                $name = $name + “.” + $extension
                $name

            <#
            .SYNOPSIS
            Adds a file name extension to a supplied name.

            .DESCRIPTION
            Adds a file name extension to a supplied name.
            Takes any strings for the file name or extension.

.PARAMETER Name
Specifies the file name.

.PARAMETER Extension
Specifies the extension. “Txt” is the default.

.INPUTS
None. You cannot pipe objects to Add-Extension.

.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.

            .EXAMPLE
            C:\PS> extension -name “File”
            File.txt

            .EXAMPLE
            C:\PS> extension -name “File” -extension “doc”
            File.doc

            .EXAMPLE
            C:\PS> extension “File” “doc”
            File.doc

.LINK
Online version: http://www.fabrikam.com/extension.html

            .LINK
            Set-Item
            #>
            }

The results are as follows:

C:\PS> Get-Help add-extension -full

NAME
Add-Extension

SYNOPSIS
Adds a file name extension to a supplied name.

SYNTAX
Add-Extension [[-Name] <String>] [[-Extension] <String>] [<CommonParameters>]

DESCRIPTION
Adds a file name extension to a supplied name. Takes any strings for the file name or extension.

        PARAMETERS
         -Name
             Specifies the file name.

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

-Extension
Specifies the extension. “Txt” is the default.

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

            <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 Add-Extension.

OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.

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

C:\PS> extension -name “File”
File.txt

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

C:\PS> extension -name “File” -extension “doc”
File.doc

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

C:\PS> extension “File” “doc”
File.doc

        RELATED LINKS
            Online version: http://www.fabrikam.com/extension.html
            Set-Item

Example 2: Parameter Descriptions in Function Syntax

        This example is the same as the previous one, except that the parameter
        descriptions are inserted in the Function syntax. This format is most
        useful when the descriptions are brief.

        Function Add-Extension
        {
            param
            (
                [string]
                # Specifies the file name.
                $name,

                [string]
                # Specifies the file name extension. “Txt” is the default.
                $extension = “txt”
            )
            $name = $name + “.” + $extension
            $name

            <#
            .SYNOPSIS
            Adds a file name extension to a supplied name.

.DESCRIPTION
Adds a file name extension to a supplied name. Takes any strings for the file name or extension.

.INPUTS
None. You cannot pipe objects to Add-Extension.

.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.

            .EXAMPLE
            C:\PS> extension -name “File”
            File.txt

            .EXAMPLE
            C:\PS> extension -name “File” -extension “doc”
            File.doc

            .EXAMPLE
            C:\PS> extension “File” “doc”
            File.doc

.LINK
Online version: http://www.fabrikam.com/extension.html

            .LINK
            Set-Item
            #>
        }

Example 3: Comment-based Help for a Script

The following sample script includes comment-based Help.

        Notice the blank lines between the closing “#>” and the Param statement.
        In a script that does not have a Param statement, there must be at least
        two blank lines between the final comment in the Help topic and the first
        Function declaration. Without these blank lines, Get-Help associates the
        Help topic with the Function, not the script.

         <#
         .SYNOPSIS
         Performs monthly data updates.

         .DESCRIPTION
         The Update-Month.ps1 script updates the Registry with new data generated
         during the past month and generates a report.

.PARAMETER InputPath
Specifies the path to the CSV-based input file.

         .PARAMETER OutputPath
         Specifies the name and path for the CSV-based output file. By default,
         MonthlyUpdates.ps1 generates a name from the date and time it runs, and
         saves the output in the local directory.

.INPUTS
None. You cannot pipe objects to Update-Month.ps1.

.OUTPUTS
None. Update-Month.ps1 does not generate any output.

.EXAMPLE
C:\PS> .\Update-Month.ps1

.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

         .EXAMPLE
         C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv
         #>

param ([string]$InputPath, [string]$OutPutPath)

Function Get-Data { }
…

        The following command gets the script Help. Because the script is not
        in a directory that is listed in the Path Environment Variable, the
        Get-Help command that gets the script Help must specify the script path.

PS C:\ps-test> Get-Help .\update-month.ps1 -full

NAME
C:\ps-test\Update-Month.ps1

SYNOPSIS
Performs monthly data updates.

            SYNTAX
                C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
                <String>] [<CommonParameters>]

            DESCRIPTION
                The Update-Month.ps1 script updates the Registry with new data
                generated during the past month and generates a report.

            PARAMETERS
             -InputPath
                 Specifies the path to the CSV-based input file.

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

             -OutputPath
                 Specifies the name and path for the CSV-based output file. By
                 default, MonthlyUpdates.ps1 generates a name from the date
                 and time it runs, and saves the output in the local directory.

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

             <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 Update-Month.ps1.

OUTPUTS
None. Update-Month.ps1 does not generate any output.

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

C:\PS> .\Update-Month.ps1

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

C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

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

C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv

RELATED LINKS

Example 4: Redirecting to an XML File

        You can write XML-based Help topics for Functions and scripts. Although
        comment-based Help is easier to implement, XML-based Help is required
        if you want more precise control over Help content or if you are
        translating Help topics into multiple languages.

        The following example shows the first few lines of the Update-Month.ps1
        script. The script uses the ExternalHelp keyword to specify the path to
        an XML-based Help topic for the script.

# .ExternalHelp C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutPutPath)

Function Get-Data { }
…

The following example shows the use of the ExternalHelp keyword in a
Function.

            Function Add-Extension
            {
                param ([string] $name, [string]$extension = “txt”)
                $name = $name + “.” + $extension
                $name

# .ExternalHelp C:\ps-test\Add-Extension.xml
}

Example 5: Redirecting to a Different Help Topic

        The following code is an excerpt from the beginning of the built-in
        Help Function in Windows PowerShell, which displays one screen of Help
        text at a time. Because the Help topic for the Get-Help cmdlet describes
        the Help Function, the Help Function uses the ForwardHelpTargetName and
        ForwardHelpCategory keywords to redirect the user to the Get-Help cmdlet
        Help topic.

Function help
{

            <#
            .FORWARDHELPTARGETNAME Get-Help
            .FORWARDHELPCATEGORY Cmdlet
            #>
            [CmdletBinding(DefaultParameterSetName=’AllUsersView’)]
            param(
                [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
                [System.String]
                ${Name},
                 …

The following command uses this feature:

C:\PS> Get-Help help

NAME
Get-Help

            SYNOPSIS
                Displays information about Windows PowerShell cmdlets and concepts.
            …

SEE ALSO
    about_functions
    about_functions_advanced_parameters
    about_scripts
    “How to Write Cmdlet Help” (http://go.microsoft.com/fwlink/?LinkID=123415)

HelpFile

about_CommonParameters

February 26, 2014 Adam

TOPIC
about_CommonParameters

SHORT DESCRIPTION
Describes the parameters that can be used with any cmdlet.

LONG DESCRIPTION
    The common parameters are a set of cmdlet parameters that you can
    use with any cmdlet. They are implemented by Windows PowerShell, not
    by the cmdlet developer, and they are automatically available to any
    cmdlet.

    You can use the common parameters with any cmdlet, but they might
    not have an effect on all cmdlets. For example, if a cmdlet does not
    generate any verbose output, using the Verbose common parameter
    has no effect.

    Several common parameters override system defaults or preferences
    that you set by using the Windows PowerShell preference Variables. Unlike
    the preference Variables, the common parameters affect only the commands
    in which they are used.

    In addition to the common parameters, many cmdlets offer the WhatIf and
    Confirm risk mitigation parameters. Cmdlets that involve risk to the system
    or to user data usually offer these parameters.

The common parameters are:

     -Verbose
     -Debug
     -WarningAction
     -WarningVariable
     -ErrorAction
     -ErrorVariable
     -OutVariable
     -OutBuffer

The risk mitigation parameters are:

-WhatIf
-Confirm

For more information about preference Variables, type:

help about_preference_variables

Common Parameter Descriptions

-Verbose[:{$true | $false}]

        Displays detailed information about the operation performed by the
        command. This information resembles the information in a trace or in
        a transaction log. This parameter works only when the command generates
        a verbose message. For example, this parameter works when a command
        contains the Write-Verbose cmdlet.

        The Verbose parameter overrides the value of the $VerbosePreference
        Variable for the current command. Because the default value of the
        $VerbosePreference Variable is SilentlyContinue, verbose messages
        are not displayed by default.

Valid values:

$true (-Verbose:$true) has the same effect as -Verbose.

            $false (-Verbose:$false) suppresses the display of verbose
            messages. Use this parameter when the value of $VerbosePreference
            is not SilentlyContinue (the default).

-Debug[:{$true | $false}]

        Displays programmer-level detail about the operation performed by the
        command. This parameter works only when the command generates
        a debugging message. For example, this parameter works when a command
        contains the Write-Debug cmdlet.

        The Debug parameter overrides the value of the $DebugPreference
        Variable for the current command. Because the default value of the
        $DebugPreference Variable is SilentlyContinue, debugging messages
        are not displayed by default.

Valid values:

$true (-Debug:$true). Has the same effect as -Debug.

            $false (-Debug:$false). Suppresses the display of debugging
            messages when the value of the $DebugPreference is not
            SilentlyContinue (the default).

-WarningAction[:{SilentlyContinue | Continue | Inquire | Stop}]

        Determines how the cmdlet responds to a warning from the command.
        “Continue” is the default value. This parameter works only
        when the command generates a warning message. For example, this
        parameter works when a command contains the Write-Warning cmdlet.

        The WarningAction parameter overrides the value of the
        $WarningPreference Variable for the current command. Because the
        default value of the $WarningPreference Variable is Continue,
        warnings are displayed and execution continues unless you use the
        WarningAction parameter.

Valid Values:

SilentlyContinue. Suppresses the warning message and continues
executing the command.

Continue. Displays the warning message and continues executing
the command. “Continue” is the default value.

            Inquire. Displays the warning message and prompts you for
            confirmation before continuing execution. This value is rarely
            used.

Stop. Displays the warning message and stops executing the
command.

-WarningVariable [+]<variable-name>

Stores warnings about the command in the specified Variable.

        To append the warnings to the Variable content, instead of replacing
        any warnings that might already be stored there, type a plus sign (+)
        before the Variable name.

For example, the following command creates the $a Variable and then
stores any warnings in it:

Get-Process -id 6 -WarningVariable a

The following command adds any warnings to the $a Variable:

Get-Process -id 2 -WarningVariable +a

The following command displays the contents of $a:

        You can use this parameter to create a Variable that contains only
        warnings from specific commands. You can use array notation, such as
        $a[0] or $warning[1,2] to refer to specific warnings stored in the
        Variable.

-ErrorAction[:{SilentlyContinue | Continue | Inquire | Stop)]

        Determines how the cmdlet responds to a non-terminating error
        from the command. This parameter works only when the command generates
        a debugging message. For example, this parameters works when a command
        contains the Write-Error cmdlet.

        The ErrorAction parameter overrides the value of the
        $ErrorActionPreference Variable for the current command.
        Because the default value of the $ErrorActionPreference Variable
        is Continue, error messages are displayed and execution continues
        unless you use the ErrorAction parameter.

        The ErrorAction parameter has no effect on terminating errors (such as
        missing data, parameters that are not valid, or insufficient
        permissions) that prevent a command from completing successfully.

Valid values:

SilentlyContinue. Suppresses the error message and continues
executing the command.

Continue. Displays the error message and continues executing
the command. “Continue” is the default value.

            Inquire. Displays the error message and prompts you for
            confirmation before continuing execution. This value is rarely
            used.

Stop. Displays the error message and stops executing the
command.

-ErrorVariable [+]<variable-name>

        Stores error messages about the command in the specified Variable
        and in the $Error automatic Variable. For more information,
        type the following command:

Get-Help about_Automatic_Variables

        By default, new error messages overwrite error messages that are
        already stored in the Variable. To append the error message to the
        Variable content, type a plus sign (+) before the Variable name.

For example, the following command creates the $a Variable and then
stores any errors in it:

Get-Process -id 6 -ErrorVariable a

The following command adds any error messages to the $a Variable:

Get-Process -id 2 -ErrorVariable +a

The following command displays the contents of $a:

        You can use this parameter to create a Variable that contains only
        error messages from specific commands. The $Error automatic
        Variable contains error messages from all the commands in the session.
        You can use array notation, such as $a[0] or $error[1,2] to refer to
        specific errors stored in the Variables.

-OutVariable [+]<variable-name>

Stores output objects from the command in the specified Variable and
displays it at the command line.

        To add the output to the Variable, instead of replacing any output
        that might already be stored there, type a plus sign (+) before the
        Variable name.

For example, the following command creates the $out Variable and
stores the process object in it:

Get-Process powershell -OutVariable out

The following command adds the process object to the $out Variable:

Get-Process iexplore -OutVariable +out

The following command displays the contents of the $out Variable:

$out

-OutBuffer <Int32>

        Determines the number of objects to accumulate in a buffer before
        any objects are sent through the pipeline. If you omit this parameter,
        objects are sent as they are generated.

        This resource management parameter is designed for advanced users.
        When you use this parameter, Windows PowerShell does not call the
        next cmdlet in the pipeline until the number of objects generated
        equals OutBuffer + 1. Thereafter, it sends all objects as they are
        generated.

Risk Management Parameter Descriptions

    -WhatIf[:{$true | $false}]
        Displays a message that describes the effect of the command,
        instead of executing the command.

        The WhatIf parameter overrides the value of the $WhatIfPreference
        Variable for the current command. Because the default value of the
        $WhatIfPreference Variable is 0 (disabled), WhatIf behavior is not
        performed without the WhatIf parameter. For more information, type
        the following command:

Get-Help about_preference_variables

Valid values:

$true (-WhatIf:$true). Has the same effect as -WhatIf.

            $false (-WhatIf:$false). Suppresses the automatic WhatIf behavior
            that results when the value of the $WhatIfPreference Variable
            is 1.

For example, the following command uses the WhatIf parameter in a
Remove-Item command:

PS> Remove-Item date.csv -whatif

        Instead of removing the item, Windows PowerShell lists the operations
        it would perform and the items that would be affected. This command
        produces the following output:

What if: Performing operation “Remove File” on
Target “C:\ps-test\date.csv”.

-Confirm[:{$true | $false}]
Prompts you for confirmation before executing the command.

        The Confirm parameter overrides the value of the $ConfirmPreference
        Variable for the current command. The default value is High. For more
        information, type the following command:

Get-Help about_preference_variables

Valid values:

$true (-WhatIf:$true). Has the same effect as -Confirm.

            $false(-Confirm:$false). Suppresses automatic confirmation,
            which occurs when the value of $ConfirmPreference is less than
            or equal to the estimated risk of the cmdlet.

        For example, the following command uses the Confirm parameter with a
        Remove-Item command. Before removing the item, Windows PowerShell
        lists the operations it would perform and the items that would be
        affected, and asks for approval.

PS C:\ps-test> Remove-Item tmp*.txt -confirm

This command produces the following output:

            Confirm
            Are you sure you want to perform this action?
            Performing operation “Remove File” on Target ” C:\ps-test\tmp1.txt
            [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend
            [?] Help (default is “Y”):

SEE ALSO
    about_preference_variables
    Write-Debug
    Write-Warning
    Write-Error
    Write-Verbose

HelpFile

about_Comparison_Operators

February 26, 2014 Adam

TOPIC
about_Comparison_Operators

SHORT DESCRIPTION
Describes the operators that compare values in Windows PowerShell.

LONG DESCRIPTION
    Comparison operators let you specify conditions for comparing values and
    finding values that match specified patterns. To use a comparison operator,
    specify the values that you want to compare together with an operator that
    separates these values.

    By default, all comparison operators are case-insensitive. To make a
    comparison operator case-sensitive, precede the operator name with a “c”.
    For example, the case-sensitive version of “-eq” is “-ceq”. To make the
    case-insensitivity explicit, precede the operator with an “i”. For example,
    the explicitly case-insensitive version of “-eq” is “ieq”.

    All comparison operators except the containment operators
    (-contains, -notcontains) and type operators (-is, -isnot) return a Boolean
    value when the input to the operator (the value on the left side of the
    operator) is a single value (a scalar). When the input is a collection of
    values, the containment operators and the type operators return any
    matching values. If there are no matches in a collection, these operators
    do not return anything. The containment operators and type operators always
    return a Boolean value.

Windows PowerShell supports the following comparison operators.

    -eq
     Description: Equal to. Includes an identical value.
     Example:

C:\PS> “abc”, “def” -eq “abc”
abc

    -ne
     Description: Not equal to. Includes a different value.
     Example:

C:\PS> “abc”, “def” -ne “abc”
def

    -gt
     Description: Greater-than.
     Example:

C:\PS> 8 -gt 6
True

    -ge
     Description: Greater-than or equal to.
     Example:

C:\PS> 8 -ge 8
True

    -lt
     Description: Less-than.
     Example:

C:\PS> 8 -lt 6
False

    -le
     Description: Less-than or equal to.
     Example:

C:\PS> 6 -le 8
True

    -like
     Description: Match using the wildcard character (*).
     Example:

C:\PS> “Windows PowerShell” -like “*shell”
True

    -notlike
     Description: Does not match using the wildcard character (*).
     Example:

C:\PS> “Windows PowerShell” -notlike “*shell”
False

    -match
     Description: Matches a string using regular expressions.
                 When the input is scalar, it populates the
                 $Matches automatic Variable.
     Example:

C:\PS> “Sunday” -match “sun”
True

         C:\PS> $matches
         Name Value
         —- —–
         0    sun

    -notmatch
     Description: Does not match a string. Uses regular expressions.
                 When the input is scalar, it populates the $Matches
                 automatic Variable.
     Example:

C:\PS> “Sunday” -notmatch “sun”
False

         C:\PS> $matches
         Name Value
         —- —–
         0    sun

    -contains
     Description: Containment operator. Includes an identical value that is
     not part of a value. Always returns a Boolean value.
     Example:

C:PS> “abc”, “def” -contains “def”
True

    -notcontains
     Description: Containment operator. Does not include an identical value.
     Always returns Boolean.
     Example:

C:PS> “Windows”, “PowerShell” -notcontains “Shell”
True

    -replace
     Description: Replace operator. Changes the specified elements of a value.
     Example:

C:\PS> “Get-Process” -replace “Get”, “Stop”
Stop-Process

Equality Operators
     The equality operators (-eq, -ne) return a value of TRUE or the matches
     when one or more of the input values is identical to the specified
     pattern. The entire pattern must match an entire value.

The following examples show the effect of the equal to operator:

C:PS> 1,2,3 -eq 2
2

C:PS> “PowerShell” -eq “Shell”
False

C:PS> “Windows”, “PowerShell” -eq “Shell”
C:PS>

C:\PS> “abc”, “def”, “123” -eq “def”
def

Containment Operators
     The containment operators (-contains and -notcontains) are similar to the
     equality operators. However, the containment operators always return a
     Boolean value, even when the input is a collection.

     Also, unlike the equality operators, the containment operators return a
     value as soon as they detect the first match. The equality operators
     evaluate all input and then return all the matches in the collection.
     The following examples show the effect of the -contains operator:

C:PS> 1,2,3 -contains 2
True

C:PS> “PowerShell” -contains “Shell”
False

C:PS> “Windows”, “PowerShell” -contains “Shell”
False

C:\PS> “abc”, “def”, “123” -contains “def”
True

C:\PS> “true”, “blue”, “six” -contains “true”
True

     The following example shows how the containment operators differ from the
     equal to operator. The containment operators return a value of TRUE on the
     first match.

         C:\PS> 1,2,3,4,5,4,3,2,1 -eq 2
         2
         2

C:\PS> 1,2,3,4,5,4,3,2,1 -contains 2
True

In a very large collection, the -contains operator returns results
quicker than the equal to operator.

Match Operators
The match operators (-match and -notmatch) find elements that match or
do not match a specified pattern using regular expressions.

The syntax is:

<string[]> -match <regular-expression>
<string[]> -notmatch <regular-expression>

The following examples show some uses of the -match operator:

C:\PS> “Windows”, “PowerShell” -match “.shell”
PowerShell

C:\PS> (Get-Command Get-Member -syntax) -match “-view”
True

C:\PS> (Get-Command Get-Member -syntax) -notmatch “-path”
True

         C:\PS> (Get-Content servers.txt) -match “^Server\d\d”
         Server01
         Server02

The match operators search only in strings. They cannot search in arrays
of integers or other objects.

     The -match and -notmatch operators populate the $Matches automatic
     Variable when the input (the left-side argument) to the operator
     is a single scalar object. When the input is scalar, the -match and
     -notmatch operators return a Boolean value and set the value of the
     $Matches automatic Variable to the matched components of the argument.

     If the input is a collection, the -match and -notmatch operators return
     the matching members of that collection, but the operator does not
     populate the $Matches Variable.

     For example, the following command submits a collection of strings to
     the -match operator. The -match operator returns the items in the collection
     that match. It does not populate the $Matches automatic Variable.

C:\PS> “Sunday”, “Monday”, “Tuesday” -match “sun”
Sunday

C:\PS> $matches
C:\PS>

     In contrast, the following command submits a single string to the
     -match operator. The -match operator returns a Boolean value and
     populates the $Matches automatic Variable.

C:\PS> “Sunday” -match “sun”
True

C:\PS> $matches

         Name                         Value
         —-                         —–
         0                             Sun

     The -notmatch operator populates the $Matches automatic Variable when
     the input is scalar and the result is False, that it, when it detects
     a match.

C:\PS> “Sunday” -notmatch “rain”
True

C:\PS> $matches
C:\PS>

C:\PS> “Sunday” -notmatch “day”
False

C:\PS> $matches
C:\PS>

         Name                         Value
         —-                         —–
         0                             day

Replace Operator
     The -replace operator replaces all or part of a value with the specified
     value using regular expressions. You can use the -replace operator for
     many administrative tasks, such as renaming files. For example, the
     following command changes the file name extensions of all .gif files
     to .jpg:

Get-ChildItem | Rename-Item -NewName { $_ -replace ‘.gif$’,’.jpg$’ }

     The syntax of the -replace operator is as follows, where the <original>
     placeholder represents the characters to be replaced, and the
     <substitute> placeholder represents the characters that will replace
     them:

     By default, the -replace operator is case-insensitive. To make it case
     sensitive, use -creplace. To make it explicitly case-insensitive, use
     -ireplace. Consider the following examples:

         C:\PS> “book” -replace “B”, “C”
         Cook
         C:\PS> “book” -ireplace “B”, “C”
         Cook
         C:\PS> “book” -creplace “B”, “C”
         book

Bitwise Operators
     Windows PowerShell supports the standard bitwise operators, including
     bitwise-AND (-band), and inclusive and exclusive bitwise-OR operators
     (-bor and -bxor). Beginning in Windows PowerShell 2.0, all bitwise
     operators work with 64-bit integers.

Windows PowerShell supports the following bitwise operators.

     Operator Description             Example
     ——– ———————-    ——————-
     -band     Bitwise AND             C:\PS> 10 -band 3
                                         2

-bor Bitwise OR (inclusive) C:\PS> 10 -bor 3
11

-bxor Bitwise OR (exclusive) C:\PS> 10 -bxor 3
9

     Bitwise operators act on the binary format of a value. For example, the
     bit structure for the number 10 is 00001010 (based on 1 byte), and the
     bit structure for the number 3 is 00000011. When you use a bitwise
     operator to compare 10 to 3, the individual bits in each byte are
     compared.

In a bitwise AND operation, the resulting bit is set to 1 only when both
input bits are 1.

         00001010     (10)
         00000011     ( 3)
         —————— bAND
         00000010     ( 2)

     In a bitwise OR (inclusive) operation, the resulting bit is set to 1
     when either or both input bits are 1. The resulting bit is set to 0 only
     when both input bits are set to 0.

         00001010     (10)
         00000011     ( 3)
         —————— bOR (inclusive)
         00001011     (11)

In a bitwise OR (exclusive) operation, the resulting bit is set to 1 only
when one input bit is 1.

         00001010     (10)
         00000011     ( 3)
         —————— bXOR (exclusive)
         00001001     ( 9)

SEE ALSO
    about_operators
    about_regular_expressions
    about_wildcards
    Compare-Object

HelpFile

about_Continue

February 26, 2014 Adam

TOPIC
about_Continue

SHORT DESCRIPTION
Describes how the Continue statement immediately returns the program flow
to the top of a program loop.

LONG DESCRIPTION
    In a script, the Continue statement immediately returns the program flow
    to the top of the innermost loop that is controlled by a For, Foreach, or
    While statement.

The Continue keyword supports labels. A label is a name you assign to a
statement in a script. For information about labels, see about_Break.

    In the following example, program flow returns to the top of the While loop
    if the $ctr Variable is equal to 5. As a result, all the numbers between 1
    and 10 are displayed except for 5:

        while ($ctr -lt 10)
             {
             $ctr +=1
             if ($ctr -eq 5) {continue}
             Write-Host $ctr
             }

    Note that in a For loop, execution continues at the first line in the
    loop. If the arguments of the For statement test a value that is
    modified by the For statement, an infinite loop may result.

SEE ALSO
about_Comparison_Operators

HelpFile

about_Core_Commands

February 26, 2014 Adam

TOPIC
about_Core_Commands

SHORT DESCRIPTION
Lists the cmdlets that are designed for use with Windows PowerShell
providers.

LONG DESCRIPTION
    Windows PowerShell includes a set of cmdlets that are specifically
    designed to manage the items in the data stores that are exposed by Windows
    PowerShell providers. You can use these cmdlets in the same ways to manage
    all the different types of data that the providers make available to you.
    For more information about providers, type “Get-Help about_providers“.

    For example, you can use the Get-ChildItem cmdlet to list the files in a
    file system directory, the keys under a Registry key, or the items that are
    exposed by a provider that you write or download.

The following is a list of the Windows PowerShell cmdlets that are designed
for use with providers:

ChildItem cmdlets
Get-ChildItem

Content cmdlets
     Add-Content
     Clear-Content
     Get-Content
     Set-Content

Item cmdlets
     Clear-Item
     Copy-Item
     Get-Item
     Invoke-Item
     Move-Item
     New-Item
     Remove-Item
     Rename-Item
     Set-Item

ItemProperty cmdlets
     Clear-ItemProperty
     Copy-ItemProperty
     Get-ItemProperty
     Move-ItemProperty
     New-ItemProperty
     Remove-ItemProperty
     Rename-ItemProperty
     Set-ItemProperty

Location cmdlets
     Get-Location
     Pop-Location
     Push-Location
     Set-Location

Path cmdlets
     Join-Path
     Convert-Path
     Split-Path
     Resolve-Path
     Test-Path

PSDrive cmdlets
     Get-PSDrive
     New-PSDrive
     Remove-PSDrive

PSProvider cmdlets
Get-PSProvider

For more information about a cmdlet, type “Get-Help <cmdlet-name>”.

SEE ALSO
about_providers

HelpFile

about_aliases

February 26, 2014 Adam

TOPIC
about_aliases

SHORT DESCRIPTION
Describes how to use alternate names for cmdlets and commands in Windows
PowerShell.

LONG DESCRIPTION
    An Alias is an alternate name or nickname for a cmdlet or for a command
    element, such as a Function, script, file, or executable file. You
    can use the Alias instead of the command name in any Windows PowerShell
    commands.

To create an Alias, use the New-Alias cmdlet. For example, the following
command creates the “gas” Alias for the Get-AuthenticodeSignature cmdlet:

New-Alias -name gas -value Get-AuthenticodeSignature

    After you create the Alias for the cmdlet name, you can use the Alias
    instead of the cmdlet name. For example, to get the Authenticode signature
    for the SqlScript.ps1 file, type:

Get-AuthenticodeSignature sqlscript.ps1

Or, type:

gas sqlscript.ps1

If you create “word” as the Alias for Microsoft Office Word, you can type
“word” instead of the following:

“c:\program files\microsoft office\office11\winword.exe”

BUILT-IN AliasES
    Windows PowerShell includes a set of built-in Aliases, including “cd” and
    “chdir” for the Set-Location cmdlet, and “ls” and “dir” for the
    Get-ChildItem cmdlet.

To get all the Aliases on the computer, including the built-in Aliases,
type:

Get-Alias

ALIAS CMDLETS
Windows PowerShell includes the following cmdlets, which are designed for
working with Aliases:

        – Get-Alias. Gets all the Aliases in the current session.
        – New-Alias. Creates a new Alias.
        – Set-Alias. Creates or changes an Alias.
        – Export-Alias. Exports one or more Aliases to a file.
        – Import-Alias. Imports an Alias file into Windows PowerShell.

For detailed information about the cmdlets, type:

Get-Help <cmdlet-name> -detailed

For example, type:

Get-Help Export-Alias -detailed

CREATING AN Alias
To create a new Alias, use the New-Alias cmdlet. For example, to create the
“gh” Alias for Get-Help, type:

New-Alias -name gh -value Get-Help

You can use the Alias in commands, just as you would use the full cmdlet
name, and you can use the Alias with parameters.

For example, to get detailed Help for the Get-WmiObject cmdlet, type:

Get-Help Get-WmiObject -detailed

Or, type:

gh Get-WmiObject -detailed

SAVING AliasES
    The Aliases that you create are saved only in the current session. To use
    the Aliases in a different session, add the Alias to your Windows
    PowerShell profile. Or, use the Export-Alias cmdlet to save the Aliases to
    a file.

For more information, type:

Get-Help about_profile

GETTING AliasES
    To get all the Aliases in the current session, including the built-in
    Aliases, the Aliases in your Windows PowerShell profiles, and the Aliases
    that you have created in the current session, type:

Get-Alias

To get particular Aliases, use the Name parameter of the Get-Alias cmdlet.
For example, to get Aliases that begin with “p”, type:

Get-Alias -name p*

To get the Aliases for a particular item, use the Definition parameter.
For example, to get the Aliases for the Get-ChildItem cmdlet type:

Get-Alias -definition Get-ChildItem

ALTERNATE NAMES FOR COMMANDS WITH PARAMETERS
    You can assign an Alias to a cmdlet, script, Function, or executable file.
    However, you cannot assign an Alias to a command and its parameters.
    For example, you can assign an Alias to the Get-EventLog cmdlet, but you
    cannot assign an Alias to the “Get-Eventlog -logname system” command.

    However, you can create a Function that includes the command. To create a
    Function, type the word “function” followed by a name for the Function.
    Type the command, and enclose it in braces ({}).

For example, the following command creates the syslog Function. This
Function represents the “Get-Eventlog -logname system” command:

Function syslog {Get-Eventlog -logname system}

You can now type “syslog” instead of the command. And, you can create
Aliases for the syslog Function.

For more information about Functions, type:

Get-Help about_functions

ALIAS OBJECTS
     Windows PowerShell Aliases are represented by objects that are instances
     of the System.Management.Automation.AliasInfo class. For more information
     about this type of object, see “AliasInfo Class” in the Microsoft
     Developer Network (MSDN) library at
     http://go.microsoft.com/fwlink/?LinkId=143644.

To view the properties and methods of the Alias objects, get the
Aliases. Then, pipe them to the Get-Member cmdlet. For example:

Get-Alias | Get-Member

     To view the values of the properties of a specific Alias, such as the
     “dir” Alias, get the Alias. Then, pipe it to the Format-List cmdlet. For
     example, the following command gets the “dir” Alias. Next, the command
     pipes the Alias to the Format-List cmdlet. Then, the command uses the
     Property parameter of Format-List with a wildcard character (*) to display
     all the properties of the “dir” Alias. The following command performs
     these tasks:

Get-Alias -name dir | Format-List -property *

WINDOWS POWERSHELL Alias PROVIDER
    Windows PowerShell includes the Alias provider. The Alias provider lets you
    view the Aliases in Windows PowerShell as though they were on a file system
    drive.

The Alias provider exposes the Alias: drive. To go into the Alias: drive,
type:

Set-Location Alias:

To view the contents of the drive, type:

Get-ChildItem

To view the contents of the drive from another Windows PowerShell drive,
begin the path with the drive name. Include the colon (:). For example:

Get-ChildItem -path Alias:

    To get information about a particular Alias, type the drive name and
    the Alias name. Or, type a name pattern. For example, to get all the
    Aliases that begin with “p”, type:

Get-ChildItem -path Alias:p*

For more information about the Windows PowerShell Alias provider,
type:

Get-Help Alias-psprovider

HelpFile

about_Arithmetic_Operators

February 26, 2014 Adam

TOPIC
about_Arithmetic_Operators

SHORT DESCRIPTION
Describes the operators that perform arithmetic in Windows PowerShell.

LONG DESCRIPTION

    Arithmetic operators calculate numeric values. You can use one or
    more arithmetic operators to add, subtract, multiply, and divide
    values, and to calculate the remainder (modulus) of a division operation.

    In addition, the addition operator (+) and multiplication operator (*)
    also operate on strings, arrays, and hash tables. The addition operator
    concatenates the input. The multiplication operator returns multiple copies
    of the input. You can even mix object types in an arithmetic statement.
    The method that is used to evaluate the statement is determined by the type
    of the leftmost object in the expression.

Windows PowerShell supports the following arithmetic operators:

    Operator Description                             Example
    ——– ———–                             ——-
    +         Adds integers; concatenates strings,    6+2
             arrays, and hash tables.                “file” + “name”

– Subtracts one value from another 6-2
value. (Get-Date).date – 1

– Makes a number a negative number. -6+2
-4

    *         Multiplies integers; copies strings     6*2
             and arrays the specified number of     “w” * 3
             times.

/ Divides two values. 6/2

% Returns the remainder of a division 7%2
operation.

OPERATOR PRECEDENCE
Windows PowerShell processes arithmetic operators in the following order:

        Parentheses ()
        – (for a negative number)
        *, /, %
        +, – (for subtraction)

    Windows PowerShell processes the expressions from left to right according
    to the precedence rules. The following examples show the effect of the
    precedence rules:

C:\PS> 3+6/3*4
11

C:\PS> 10+4/2
12

C:\PS> (10+4)/2
7

C:\PS> (3+3)/ (1+1)
3

    The order in which Windows PowerShell evaluates expressions might differ
    from other programming and scripting languages that you have used. The
    following example shows a complicated assignment statement.

        C:\PS> $a = 0
        C:\PS> $b = 1,2
        C:\PS> $c = -1,-2

C:\PS> $b[$a] = $c[$a++]

        C:\PS> $b
        1
        -1

    In this example, the expression $a++ is evaluated before $c[$a++].
    Evaluating $a++ changes the value of $a. The Variable $a in $b[$a]
    equals 1, not 0, so the statement assigns a value to $b[1], not $b[0].

    ADDING AND MULTIPLYING NON-NUMERIC TYPES
    You can add numbers, strings, arrays, and hash tables. And, you can
    multiply numbers, strings, and arrays. However, you cannot multiply hash
    tables.

    When you add strings, arrays, or hash tables, the elements are
    concatenated. When you concatenate collections, such as arrays or hash
    tables, a new object is created that contains the objects from both
    collections. If you try to concatenate hash tables that have the same key,
    the operation fails.

For example, the following commands create two arrays and then add them:

    C:\PS> $a = 1,2,3
    C:\PS> $b = “A”,”B,”C”
    C:\PS> $a + $b
    1
    2
    3
    A
    B
    C

    You can also perform arithmetic operations on objects of different types.
    The operation that Windows PowerShell performs is determined by the
    Microsoft .NET Framework type of the leftmost object in the operation.
    Windows PowerShell tries to convert all the objects in the operation to the
    .NET Framework type of the first
    object. If it succeeds in converting the objects, it performs the operation
    appropriate to the .NET Framework type of the first object. If it fails to
    convert any of the objects, the operation fails.

The following example demonstrates the use of the addition and
multiplication operators in operations that include different object types:

C:\PS> “file” + 16
file16

        C:\PS> $array = 1,2,3
        C:\PS> $array + 16
        1
        2
        3
        16

    C:\PS> $array + “file”
        1
        2
        3
        file

C:\PS> “file” * 3
filefilefile

    Because the method that is used to evaluate statements is determined by the
    leftmost object, addition and multiplication in Windows PowerShell are not
    strictly commutative. For example, (a + b) does not always equal (b + a),
    and (a * b) does not always equal (b * a).

The following examples demonstrate this principle:

C:\PS> “file” + 2
file2

        C:\PS> 2 + “file”
        Cannot convert value “file” to type “System.Int32”. Error: “Input
        string was not in a correct format.”
        At line:1 char:4
        + 2 + <<<< “file”

C:\PS> “file” * 3
filefilefile

        C:\PS> 3 * “file”
        Cannot convert value “file” to type “System.Int32”. Error: “Input
        string was not in a correct format.”
        At line:1 char:4
        + 3 * <<<< “file”

    Hash tables are a slightly different case. You can add hash tables. And,
    you can add a hash table to an array. However, you cannot add any other
    type to a hash table.

The following examples show how to add hash tables to each other and to
other objects:

        C:\PS> $hash1 = @{a=1; b=2; c=3}
        C:\PS> $hash2 = @{c1=”Server01″; c2=”Server02″}
        C:\PS> $hash1 + $hash2

        Name                         Value
        —-                         —–
        c2                             Server02
        a                             1
        b                             2
        c1                             Server01
        c                             3

        C:\PS> $hash1 + 2
        You can add another hash table only to a hash table.
        At line:1 char:9
        + $hash1 + <<<< 2

        C:\PS> 2 + $hash1
        Cannot convert “System.Collections.Hashtable” to “System.Int32”.
        At line:1 char:4
        + 2 + <<<< $hash1

The following examples demonstrate that you can add a hash table to an
array. The entire hash table is added to the array as a single object.

        C:\PS> $array = 1,2,3
        C:\PS> $array + $hash1
        1
        2
        3

        Name                         Value
        —-                         —–
        a                             1
        b                             2
        c                             3

        C:\PS> $sum = $array + $hash1
        C:\PS> $sum.count
        4

        C:\PS> $sum[3]
        Name                         Value
        —-                         —–
        a                             1
        b                             2
        c                             3

        PS C:\ps-test> $sum + $hash2
        1
        2
        3

        Name                         Value
        —-                         —–
        a                             1
        b                             2
        c                             3
        c2                             Server02

The following example shows that you cannot add hash tables that contain
the same key:

        C:\PS> $hash1 = @{a=1; b=2; c=3}
        C:\PS> $hash2 = @{c=”red”}
        C:\PS> $hash1 + $hash2
        Bad argument to operator ‘+’: Item has already been added.
        Key in dictionary: ‘c’    Key being added: ‘c’.
        At line:1 char:9
        + $hash1 + <<<< $hash2

    Although the addition operators are very useful, use the assignment
    operators to add elements to hash tables and arrays. For more information
    see about_Assignment_Operators. The following examples use the +=
    assignment operator to add items to an array:

        C:\PS> $array
        1
        2
        3

        C:\PS> $array + “file”
        1
        2
        3
        file

        C:\PS> $array
        1
        2
        3

        C:\PS> $array += “file”
        C:\PS> $array
        1
        2
        3
        file

C:\PS> $hash1

C:\PS> $hash1 += @{e = 5}
C:\PS> $hash1

        Name                         Value
        —-                         —–
        a                             1
        b                             2
        e                             5
        c                             3

Windows PowerShell automatically selects the .NET Framework numeric type
that best expresses the result without losing precision. For example:

        C:\PS> 2 + 3.1
        5.1
        C:\PS> (2). GetType().FullName
        System.Int32
        C:\PS> (2 + 3.1).GetType().FullName
        System.Double

If the result of an operation is too large for the type, the type of the
result is widened to accommodate the result, as in the following example:

        C:\PS> (512MB).GetType().FullName
        System.Int32
        C:\PS> (512MB * 512MB).GetType().FullName
        System.Double

    The type of the result will not necessarily be the same as one of the
    operands. In the following example, the negative value cannot be cast to an
    unsigned integer, and the unsigned integer is too large to be cast to
    Int32:

C:\PS> ([int32]::minvalue + [uint32]::maxvalue).gettype().fullname
System.Int64

In this example, Int64 can accommodate both types.

    The System.Decimal type is an exception. If either operand has the Decimal
    type, the result will be of the Decimal type. If the result is too large
    for the Decimal type, it will not be cast to Double. Instead, an error
    results.

        C:\PS> [Decimal]::maxvalue
        79228162514264337593543950335
        C:\PS> [Decimal]::maxvalue + 1
        Value was either too large or too small for a Decimal.
        At line:1 char:22
        + [Decimal]::maxvalue + <<<< 1

    ARITHMETIC OPERATORS AND VariableS
    You can also use arithmetic operators with Variables. The operators act on
    the values of the Variables. The following examples demonstrate the use of
    arithmetic operators with Variables:

        C:\PS> $intA = 6
        C:\PS> $intB = 4
        C:\PS> $intA + $intB

        C:\PS> $a = “Windows ”
        C:\PS> $b = “PowerShell ”
        C:\PS> $c = 2
    C:\PS> $a + $b + $c

Windows PowerShell 2

    ARITHMETIC OPERATORS AND COMMANDS
    Typically, you use the arithmetic operators in expressions with numbers,
    strings, and arrays. However, you can also use arithmetic operators with
    the objects that commands return and with the properties of those objects.

The following examples show how to use the arithmetic operators in
expressions with Windows PowerShell commands:

C:\PS> Get-Date
Wednesday, January 02, 2008 1:28:42 PM

    C:\PS> $day = New-TimeSpan -day 1
    C:\PS> Get-Date + $day
    Thursday, January 03, 2008 1:34:52 PM

    C:\PS> Get-Process | where {($_.ws * 2) -gt 50mb}
    Handles NPM(K)    PM(K)     WS(K) VM(M) CPU(s)     Id ProcessName
    ——- ——    —–     —– —– ——     — ———–
     1896     39    50968     30620 264 1,572.55 1104 explorer
     12802     78 188468     81032 753 3,676.39 5676 OUTLOOK
        660     9    36168     26956 143    12.20    988 powershell
        561     14     6592     28144 110 1,010.09    496 services
     3476     80    34664     26092 234 …45.69    876 svchost
        967     30    58804     59496 416 930.97 2508 WINWORD

EXAMPLES
The following examples show how to use the arithmetic operators in
Windows PowerShell:

C:\PS> 1 + 1
2

C:\PS> 1 – 1
0

C:\PS> -(6 + 3)
-9

C:\PS> 6 * 2
12

C:\PS> 7 / 2
3.5

C:\PS> 7 % 2
1

C:\PS> w * 3
www

    C:\PS> 3 * “w”
    Cannot convert value “w” to type “System.Int32”. Error: “Input string was not
        in a correct format.”
    At line:1 char:4
    + 3 * <<<< “w”

PS C:\ps-test> “Windows” + ” ” + “PowerShell”
Windows PowerShell

    PS C:\ps-test> $a = “Windows” + ” ” + “PowerShell”
    PS C:\ps-test> $a
    Windows PowerShell

C:\PS> $a[0]
W

    C:\PS> $a = “TestFiles.txt”
    C:\PS> $b = “C:\Logs\”
    C:\PS> $b + $a
    C:\Logs\TestFiles.txt

    C:\PS> $a = 1,2,3
    C:\PS> $a + 4
    1
    2
    3
    4

    C:\PS> $servers = @{0 = “LocalHost”; 1 = “Server01”; 2 = “Server02”}
    C:\PS> $servers + @{3 = “Server03”}
    Name Value
    —- —–
    3 Server03
    2 Server02
    1 Server01
    0 LocalHost

    C:\PS> $servers
    Name Value
    —- —–
    2 Server02
    1 Server01
    0 LocalHost

    C:\PS> $servers += @{3 = “Server03”} #Use assignment operator
    C:\PS> $servers
    Name Value
    —- —–
    3 Server03
    2 Server02
    1 Server01
    0 LocalHost

HelpFile

about_arrays

February 26, 2014 Adam

TOPIC
about_arrays

SHORT DESCRIPTION
Describes a compact data structure for storing data elements.

LONG DESCRIPTION
    An array is a data structure for storing a collection of data elements
    of the same type. Windows PowerShell supports data elements, such as
    string, int (32-bit integer), long (64-bit integer), bool (Boolean), byte,
    and other Microsoft .NET Framework object types.

CREATING AND INITIALIZING AN ARRAY
    To create and initialize an array, assign multiple values to a Variable.
    The values stored in the array are delimited with a comma and separated
    from the Variable name by the assignment operator (=).

For example, to create an array named $A that contains the seven
numeric (int) values of 22, 5, 10, 8, 12, 9, and 80, type:

$A = 22,5,10,8,12,9,80

    You can also create and initialize an array by using the range
    operator (..). For example, to create and initialize an array named
    “$B” that contains the values 5 through 8, type:

$B = 5..8

As a result, $B contains four values: 5, 6, 7, and 8.

    When no data type is specified, Windows PowerShell creates each array as
    an object array (type: object[]). To determine the data type of an array,
    use the GetType() method. For example, to determine the data type of the
    $a array, type:

$a.gettype()

    To create a strongly typed array, that is, an array that can contain only
    values of a particular type, cast the Variable as an array type, such
    as string[], long[], or int32[]. To cast an array, precede the Variable
    name with an array type enclosed in brackets. For example, to create a
    32-bit integer array named $ia containing four integers (1500, 2230, 3350,
    and 4000), type:

[int32[]]$ia = 1500,2230,3350,4000

As a result, the $ia array can contain only integers.

    You can create arrays that are cast to any supported type in the
    Microsoft .NET Framework. For example, the objects that Get-Process
    retrieves to represent processes are of the System.Diagnostics.Process
    type. To create a strongly typed array of process objects, enter the
    following command:

[Diagnostics.Process[]]$zz = Get-Process

    You can populate an array by using the output of a cmdlet, Function, or
    statement. For example, the following statement creates an array that
    contains the processes that start with the letters “co” and that are
    running on the current computer:

$LocalProcesses = Get-Process co*

    If the statement gets only a single process, the $LocalProcesses Variable
    would not be an array. To ensure the command creates an array, use the
    array subexpression operator, @, as shown in the following example:

$LocalProcesses = @(Get-Process co*)

    Even if the command returns a single process, the $LocalProcesses Variable
    is an array. Even if it has only one member, you can treat it like any
    other array. For example, you can add other objects to it. For more
    information, see about_operators.

READING AN ARRAY
You can refer to an array by using its Variable name, such as $A or $a.
Windows PowerShell is not case-sensitive.

To display all the elements in the array, type the array name. For example:

    You can refer to the elements in an array by using an index, beginning
    at position 0. Enclose the index number in brackets. For example,
    to display the first element in the $a array, type:

$a[0]

To display the third element in the $a array, type:

$a[2]

    Negative numbers count from the end of the array. For example, “-1”
    refers to the last element of the array. To display the last three elements
    of the array, type:

$a[-3..-1]

However, be cautious when using this notation.

$a[0..-2]

    This command does not refer to all the elements of the array, except for
    the last one. It refers to the first, last, and second-to-last elements
    in the array.

    You can use the range operator to display a subset of all the values in an
    array. For example, to display the data elements at index position 1
    through 3, type:

$a[1..3]

    You can use the plus operator (+) to combine a range with a list of
    elements in an array. For example, to display the elements at index
    positions 0, 2, and 4 through 6, type:

$a[0,2+4..6]

    To determine how many items are in an array, combine the range with the
    length property of an array. For example, to display the elements from
    index position 2 to the end of the array, type:

$a[2..($a.length-1)]

    The length is set to -1 because the index begins at position 0. Therefore,
    in a three-element array (1,2,3), the index of the third element is 2,
    which is one less than the length of the array.

    You can also use looping constructs, such as Foreach, For, and While loops,
    to refer to the elements in an array. For example, to use a Foreach loop
    to display the elements in the $a array, type:

foreach ($element in $a) {$element}

The Foreach loop iterates through the array and returns each value in
the array until reaching the end of the array.

    The For loop is useful when you are incrementing counters while examining
    the elements in an array. For example, to return every other value in an
    array by using a For loop, type:

for ($i = 0; $i -le ($a.length – 1); $i += 2) {$a[$i]}

    You can use a While loop to display the elements in an array until a
    defined condition is no longer true. For example, to display the elements
    in the $a array while the array index is less than 4, type:

$i=0
while($i -lt 4) {$a[$i]; $i++}

    To learn about the properties and methods of an array, such as the Length
    property and the SetValue method, use the InputObject parameter of the
    Get-Member cmdlet. When you pipe an array to Get-Member, it displays
    information about the objects in the array. When you use the InputObject
    parameter, it displays information about the array.

To find the properties and methods of the $a array, type:

Get-Member -inputobject $a

MANIPULATING AN ARRAY
You can change the elements in an array, add an element to an array, and
combine the values from two arrays into a third array.

    To change the value of a particular element in an array, specify the
    array name and the index of the element that you want to change, and then
    use the assignment operator (=) to specify a new value for the element. For
    example, to change the value of the second item in the $a array (index
    position 1) to 10, type:

$a[1] = 10

    You can also use the SetValue method of an array to change a value. The
    following example changes the second value (index position 1) of the $a
    array to 500:

$a.SetValue(500,1)

    You can append an element to an existing array by using the += operator.
    This operator adds to an existing value. When the operator is used on an
    element of an array, it increases the value of the element. When the
    operator is used on the array itself, it appends the value. For example,
    to append an element with a value of 200 to the $a array, type:

$a += 200

    It is not easy to delete elements from an array, but you can create a new
    array that contains only selected elements of an existing array. For
    example, to create the $t array with all the elements in the $a array
    except for the value at index position 2, type:

$t = $a[0,1 + 3..($a.length – 1)]

    To combine two arrays into a single array, use the plus operator (+). The
    following example creates two arrays, combines them, and then displays
    the resulting combined array.

        $x = 1,3
        $y = 5,9
        $z = $x + $y

As a result, the $z array contains 1, 3, 5, and 9.

    To delete an array, use the Remove-Item cmdlet to delete the Variable that
    contains the array. The following command specifies the element “a” in the
    Variable: drive.

Remove-Item Variable:a

(For more information about the Variable: drive, see the Variable provider
Help topic.)

SEE ALSO
    about_Assignment_Operators
    about_hash_tables
    about_operators
    about_For
    about_Foreach
    about_While

HelpFile

about_Assignment_Operators

February 26, 2014 Adam

TOPIC
about_Assignment_Operators

SHORT DESCRIPTION
Describes how to use operators to assign values to Variables.

LONG DESCRIPTION
Assignment operators assign one or more values to a Variable. They can
perform numeric operations on the values before the assignment.

Windows PowerShell supports the following assignment operators.

    Operator Description
    ——- ———–
    =         Sets the value of a Variable to the specified value.

+= Increases the value of a Variable by the specified value, or
appends the specified value to the existing value.

-= Decreases the value of a Variable by the specified value.

*= Multiplies the value of a Variable by the specified value, or
appends the specified value to the existing value.

/= Divides the value of a Variable by the specified value.

%= Divides the value of a Variable by the specified value and
then assigns the remainder (modulus) to the Variable.

++ Increases the value of a Variable, assignable property, or
array element by 1.

— Decreases the value of a Variable, assignable property, or
array element by 1.

SYNTAX
The syntax of the assignment operators is as follows:

<assignable-expression> <assignment-operator> <value>

Assignable expressions include Variables and properties. The value can be
a single value, an array of values, or a command, expression, or statement.

The increment and decrement operators are unary operators. Each has prefix
and postfix versions.

<assignable-expression><operator>
<operator><assignable-expression>

The assignable expression must a number or it must be convertible to a
number.

ASSIGNING VALUES
    Variables are named memory spaces that store values. You store the values
    in Variables by using the assignment operator (=). The new value can
    replace the existing value of the Variable, or you can append a new value
    to the existing value.

    The basic assignment operator is the equal sign (=)(ASCII 61). For example,
    the following statement assigns the value Windows PowerShell to the
    $MyShell Variable:

$MyShell = “Windows PowerShell”

    When you assign a value to a Variable in Windows PowerShell, the Variable
    is created if it did not already exist. For example, the first of the
    following two assignement statements creates the $a Variable and assigns
    a value of 6 to $a. The second assignment statement assigns a value
    of 12 to $a. The first statement creates a new Variable. The second
    statement changes only its value:

$a = 6
$a = 12

    Variables in Windows PowerShell do not have a specific data type unless you
    cast them. When a Variable contains only one object, the Variable takes the
    data type of that object. When a Variable contains a collection of objects,
    the Variable has the System.Object data type. Therefore, you can assign any
    type of object to the collection. The following example shows that you can
    add process objects, service objects, strings, and integers to a Variable
    without generating an error:

        $a = Get-Process
        $a += Get-Service
        $a += “string”
        $a += 12

    Because the assignment operator (=) has a lower precedence than the
    pipeline operator (|), parentheses are not required to assign the result
    of a command pipeline to a Variable. For example, the following command
    sorts the services on the computer and then assigns the sorted services
    to the $a Variable:

$a = Get-Service | sort name

You can also assign the value created by a statement to a Variable, as in
the following example:

$a = if ($b -lt 0) { 0 } else { $b }

    This example assigns 0 to the $a Variable if the value of $b is less
    than 0. It assigns the value of $b to $a if the value of $b is not less
    than zero.

THE ASSIGNMENT OPERATOR (=)
    The assignment operator (=) assigns values to Variables. If the Variable
    already has a value, the assignment operator (=) replaces the value
    without warning.

The following statement assigns the integer value 6 to the $a Variable:

$a = 6

To assign a string value to a Variable, enclose the string value in
quotation marks, as follows:

$a = “baseball”

To assign an array (multiple values) to a Variable, separate the values
with commas, as follows:

$a = “apple”, “orange”, “lemon”, “grape”

    To assign a hash table to a Variable, use the standard hash table notation
    in Windows PowerShell. Type an at sign (@) followed by key/value pairs that
    are separated by semicolons (;) and enclosed in braces ({ }). For example,
    to assign a hash table to the $a Variable, type:

$a = @{one=1; two=2; three=3}

    To assign hexadecimal values to a Variable, precede the value with “0x”.
    Windows PowerShell converts the hexadecimal value (0x10) to a decimal
    value (in this case, 16) and assigns that value to the $a Variable. For
    example, to assign a value of 0x10 to the $a Variable, type:

$a = 0x10

    To assign an exponential value to a Variable, type the root number, the
    letter “e”, and a number that represents a multiple of 10. For example, to
    assign a value of 3.1415 to the power of 1,000 to the $a Variable, type:

$a = 3.1415e3

    Windows PowerShell can also convert kilobytes (KB), megabytes (MB), and
    gigabytes (GB) into bytes. For example, to assign a value of 10 kilobytes
    to the $a Variable, type:

$a = 10kb

THE ASSIGNMENT BY ADDITION OPERATOR (+=)
    The assignment by addition operator (+=) either increments the value of a
    Variable or appends the specified value to the existing value. The action
    depends on whether the Variable has a numeric or string type and whether
    the Variable contains a single value (a scalar) or multiple values
    (a collection).

The += operator combines two operations. First, it adds, and then it
assigns. Therefore, the following statements are equivalent:

$a += 2
$a = ($a + 2)

    When the Variable contains a single numeric value, the += operator
    increments the existing value by the amount on the right side of the
    operator. Then, the operator assigns the resulting value to the Variable.
    The following example shows how to use the += operator to increase the
    value of a Variable:

        C:\PS> $a = 4
        C:\PS> $a += 2
        C:\PS> $a
        6

When the value of the Variable is a string, the value on the right side of
the operator is appended to the string, as follows:

        C:\PS> $a = “Windows”
        C:\PS> $a +- ” PowerShell”
        C:\PS> $a
        Windows PowerShell

    When the value of the Variable is an array, the += operator appends the
    values on the right side of the operator to the array. Unless the array is
    explicitly typed by casting, you can append any type of value to the array,
    as follows:

        C:\PS> $a = 1,2,3
        C:\PS> $a += 2
        C:\PS> $a
        1
        2
        3
        2
        C:\PS> $a += “String”
        C:\PS> $a
        1
        2
        3
        2
        String

    When the value of a Variable is a hash table, the += operator appends the
    value on the right side of the operator to the hash table. However, because
    the only type that you can add to a hash table is another hash table, all
    other assignments fail.

    For example, the following command assigns a hash table to the $a Variable.
    Then, it uses the += operator to append another hash table to the existing
    hash table, effectively adding a new key/value pair to the existing hash
    table. This command succeeds, as shown in the output:

        C:\PS> $a = @{a = 1; b = 2; c = 3}
        C:\PS> $a += @{mode = “write”}
        C:\PS> $a
        Name                         Value
        —-                         —–
        a                             1
        b                             2
        mode                         write
        c                             3

The following command attempts to append an integer (1) to the hash table
in the $a Variable. This command fails:

        C:\PS> $a = @{a = 1; b = 2; c = 3}
        C:\PS> $a += 1
        You can add another hash table only to a hash table.
        At line:1 char:6
        + $a += <<<< 1

THE ASSIGNMENT BY SUBTRACTION OPERATOR (-=)
    The assignment by subtraction operator (-=) decrements the value of a
    Variable by the value that is specified on the right side of the operator.
    This operator cannot be used with string Variables, and it cannot be used
    to remove an element from a collection.

The -= operator combines two operations. First, it subtracts, and then it
assigns. Therefore, the following statements are equivalent:

$a -= 2
$a = ($a – 2)

The following example shows how to use of the -= operator to decrease the
value of a Variable:

        C:\PS> $a = 8
        C:\PS> $a -= 2
        C:\PS> $a
        6

    You can also use the -= assignment operator to decrease the value of a
    member of a numeric array. To do this, specify the index of the array
    element that you want to change. In the following example, the value of the
    third element of an array (element 2) is decreased by 1:

        C:\PS> $a = 1,2,3
        C:\PS> $a[2] -= 1.
        C:\PS> $a
        1
        2
        2

    You cannot use the -= operator to delete the values of a Variable. To
    delete all the values that are assigned to a Variable, use the Clear-Item
    or Clear-Variable cmdlets to assign a value of $null or “” to the Variable.

$a = $null

    To delete a particular value from an array, use array notation to assign a
    value of $null to the particular item. For example, the following statement
    deletes the second value (index position 1) from an array:

        C:\PS> $a = 1,2,3
        C:\PS> $a
        1
        2
        3

        C:\PS> $a[1] = $null
        C:\PS> $a
        1
        3

    To delete a Variable, use the Remove-Variable cmdlet. This method is useful
    when the Variable is explicitly cast to a particular data type, and you
    want an untyped Variable. The following command deletes the $a Variable:

Remove-Variable a

THE ASSIGNMENT BY MULTIPLICATION OPERATOR (*=)
    The assignment by multiplication operator (*=) multiplies a numeric value
    or appends the specified number of copies of the string value of a
    Variable.

    When a Variable contains a single numeric value, that value is multiplied
    by the value on the right side of the operator. For example, the following
    example shows how to use the *= operator to multiply the value of a
    Variable:

        C:\PS> $a = 3
        C:\PS> $a *= 4
        C:\PS> $a
        12

    In this case, the *= operator combines two operations. First, it
    multiplies, and then it assigns. Therefore, the following statements are
    equivalent:

$a *= 2
$a = ($a * 2)

When a Variable contains a string value, Windows PowerShell appends the
specified number of strings to the value, as follows:

        C:\PS> $a = “file”
        C:\PS> $a *= 4
        C:\PS> $a
        filefilefilefile

    To multiply an element of an array, use an index to identify the element
    that you want to multiply. For example, the following command multiplies
    the first element in the array (index position 0) by 2:

$a[0] *= 2

THE ASSIGNMENT BY DIVISION OPERATOR (/=)
    The assignment by division operator (/=) divides a numeric value by the
    value that is specified on the right side of the operator. The operator
    cannot be used with string Variables.

The /= operator combines two operations. First, it divides, and then it
assigns. Therefore, the following two statements are equivalent:

$a /= 2
$a = ($a / 2)

For example, the following command uses the /= operator to divide the value
of a Variable:

        C:\PS> $a = 8
        C:\PS> $a /=2
        C:\PS> $a
        4

    To divide an element of an array, use an index to identify the element that
    you want to change. For example, the following command divides the second
    element in the array (index position 1) by 2:

$a[1] /= 2

THE ASSIGNMENT BY MODULUS OPERATOR (%=)
    The assignment by modulus operator (%=) divides the value of a Variable by
    the value on the right side of the operator. Then, the %= operator assigns
    the remainder (known as the modulus) to the Variable. You can use this
    operator only when a Variable contains a single numeric value. You cannot
    use this operator when a Variable contains a string Variable or an array.

    The %= operator combines two operations. First, it divides and determines
    the remainder, and then it assigns the remainder to the Variable.
    Therefore, the following statements are equivalent:

$a %= 2
$a = ($a % 2)

The following example shows how to use the %= operator to save the modulus
of a quotient:

        C:\PS> $a = 7
        C:\PS> $a %= 4
        C:\PS> $a
        3

THE INCREMENT AND DECREMENT OPERATORS

    The increment operator (++) increases the value of a Variable by 1. When
    you use the increment operator in a simple statement, no value is returned.
    To view the result, display the value of the Variable, as follows:

        C:\PS> $a = 7
        C:\PS> ++$a
        C:\PS> $a
        8

To force a value to be returned, enclose the Variable and the operator in
parentheses, as follows:

        C:\PS> $a = 7
        C:\PS> (++$a)
        8

    The increment operator can be placed before (prefix) or after (postfix) a
    Variable. The prefix version of the operator increments a Variable before
    its value is used in the statement, as follows:

        C:\PS> $a = 7
        C:\PS> $c = ++$a
        C:\PS> $a
        8
        C:\PS> $c
        8

    The postfix version of the operator increments a Variable after its value
    is used in the statement. In the following example, the $c and $a Variables
    have different values because the value is assigned to $c before $a
    changes:

        C:\PS> $a = 7
        C:\PS> $c = $a++
        C:\PS> $a
        8
        C:\PS> $c
        7

    The decrement operator (–) decreases the value of a Variable by 1. As with
    the increment operator, no value is returned when you use the operator in a
    simple statement. Use parentheses to return a value, as follows:

        C:\PS> $a = 7
        C:\PS> –$a
        C:\PS> $a
        6
        C:\PS> (–$a)
        5

The prefix version of the operator decrements a Variable before its value
is used in the statement, as follows:

        C:\PS> $a = 7
        C:\PS> $c = –$a
        C:\PS> $a
        6
        C:\PS> $c
        6

    The postfix version of the operator decrements a Variable after its value
    is used in the statement. In the following example, the $d and $a Variables
    have different values because the value is assigned to $d before $a
    changes:

        C:\PS> $a = 7
        C:\PS> $d = $a–
        C:\PS> $a
        6
        C:\PS> $d
        7

MICROSOFT .NET FRAMEWORK TYPES
    By default, when a Variable has only one value, the value that is assigned
    to the Variable determines the data type of the Variable. For example, the
    following command creates a Variable that has the Integer (System.Int32)
    type:

$a = 6

    To find the .NET Framework type of a Variable, use the GetType method and
    its FullName property, as follows. Be sure to include the parentheses after
    the GetType method name, even though the method call has no arguments:

        C:\PS> $a = 6
        C:\PS> $a.gettype().fullname
        System.Int32

    To create a Variable that contains a string, assign a string value to the
    Variable. To indicate that the value is a string, enclose it in quotation
    marks, as follows:

        C:\PS> $a = “6”
        C:\PS> $a.gettype().fullname
        System.String

    If the first value that is assigned to the Variable is a string, Windows
    PowerShell treats all operations as string operations and casts new values
    to strings. This occurs in the following example:

        C:\PS> $a = “file”
        C:\PS> $a += 3
        C:\PS> $a
        file3

    If the first value is an integer, Windows PowerShell treats all operations
    as integer operations and casts new values to integers. This occurs in the
    following example:

        C:\PS> $a = 6
        C:\PS> $a += “3”
        C:\PS> $a
        9

    You can cast a new scalar Variable as any .NET Framework type by placing
    the type name in brackets that precede either the Variable name or
    the first assignment value. When you cast a Variable, you can determine the
    types of data that can be stored in the Variable. And, you can determine
    how the Variable behaves when you manipulate it.

For example, the following command casts the Variable as a string type:

        C:\PS> [string]$a = 27
        C:\PS> $a += 3
        C:\PS> $a
        273

The following example casts the first value, instead of casting the
Variable:

$a = [string]27

    When you cast a Variable to a specific type, the common convention is to
    cast the Variable, not the value. However, you cannot recast the data type
    of an existing Variable if its value cannot be converted to the new data
    type. To change the data type, you must replace its value, as follows:

        C:\PS> $a = “string”
        C:\PS> [int]$a
        Cannot convert value “string” to type “System.Int32”. Error: “Input
        string was not in a correct format.”
        At line:1 char:8
        + [int]$a <<<<

C:\PS> [int]$a =3

    In addition, when you precede a Variable name with a data type, the type
    of that Variable is locked unless you explicitly override the type by
    specifying another data type. If you try to assign a value that is
    incompatible with the existing type, and you do not explicitly override the
    type, Windows PowerShell displays an error, as shown in the following
    example:

C:\PS> $a = 3
C:\PS> $a = “string”

        C:\PS> [int]$a = 3
        C:\PS> $a = “string”
        Cannot convert value “string” to type “System.Int32”. Error: “Input
        string was not in a correct format.”
        At line:1 char:3
        + $a <<<< = “string”

C:\PS> [string]$a = “string”

    In Windows PowerShell, the data types of Variables that contain multiple
    items in an array are handled differently from the data types of Variables
    that contain a single item. Unless a data type is specifically assigned to
    an array Variable, the data type is always System.Object []. This data type
    is specific to arrays.

    Sometimes, you can override the default type by specifying another
    type. For example, the following command casts the Variable as a string []
    array type:

[string []] $a = “one”, “two”, “three”

    Windows PowerShell Variables can be any .NET Framework data type. In
    addition, you can assign any fully qualified .NET Framework data type that
    is available in the current process. For example, the following command
    specifies a System.DateTime data type:

[system.datetime]$a = “5/31/2005”

The Variable will be assigned a value that conforms to the System.DateTime
data type. The value of the $a Variable would be the following:

Tuesday, May 31, 2005 12:00:00 AM

ASSIGNING MULTIPLE VariableS
    In Windows PowerShell, you can assign values to multiple Variables by using
    a single command. The first element of the assignment value is assigned to
    the first Variable, the second element is assigned to the second Variable,
    the third element to the third Variable, and so on. For example, the
    following command assigns the value 1 to the $a Variable, the value 2 to
    the $b Variable, and the value 3 to the $c Variable:

C:\PS> $a, $b, $c = 1, 2, 3

    If the assignment value contains more elements than Variables, all the
    remaining values are assigned to the last Variable. For example, the
    following command contains three Variables and five values:

$a, $b, $c = 1, 2, 3, 4, 5

    Therefore, Windows PowerShell assigns the value 1 to the $a Variable and
    the value 2 to the $b Variable. It assigns the values 3, 4, and 5 to
    the $c Variable. To assign the values in the $c Variable to three other
    Variables, use the following format:

$d, $e, $f = $c

This command assigns the value 3 to the $d Variable, the value 4 to
the $e Variable, and the value 5 to the $f Variable.

    You can also assign a single value to multiple Variables by chaining the
    Variables. For example, the following command assigns a value of “three”
    to all four Variables:

$a = $b = $c = $d = “three”

Variable-RELATED CMDLETS
    In addition to using an assignment operation to set a Variable value, you
    can also use the Set-Variable cmdlet. For example, the following command
    uses Set-Variable to assign an array of 1, 2, 3 to the $a Variable.

Set-Variable -name a -value 1, 2, 3

SEE ALSO
    about_arrays
    about_hash_tables
    about_Variables
    Clear-Variable
    Remove-Variable
    Set-Variable