Tag Archives: Value

cmdlet, Set, Variable

Set-Variable

NAME
    Set-Variable

SYNOPSIS
    Sets the value of a Variable. Creates the Variable if one with the requested name does not exist.

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

DESCRIPTION
    The Set-Variable cmdlet assigns a value to a specified Variable or changes the current value. If the Variable does not exist, the cmdlet creates it.

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

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

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

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

    -Force [<SwitchParameter>]
        Allows you to create a Variable with the same name as an existing read-only Variable, or to change the value of a read-only Variable.

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

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

    -Include <string[]>
        Changes only the specified items. The value of this parameter qualifies the Name parameter. Enter a name or name pattern, such as “c*”. Wildcards are permitted.

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

    -Name <string[]>
        Specifies the Variable name.

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

    -Option <ScopedItemOptions>
        Changes the value of the Options property of the Variable. Valid values are:

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

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

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

        — Private: The Variable is available only within the scope specified by the Scope parameter. It is inherited by child scopes.

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

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

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

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

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

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

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

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

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

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

        Valid values are:

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

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

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

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

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

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

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

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.Object
        You can pipe an object that represents the value of the Variable to Set-Variable.

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

NOTES

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

    C:\PS>Set-Variable -Name desc -Value “A description”

    C:\PS>Get-Variable -Name desc

    Description
    ———–
    These commands set the value of the “desc” Variable to “A description”, and then get the value of the Variable.

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

    C:\PS>Set-Variable -Name processes -Value (Get-Process) -Option constant -Scope global -Description “All processes” -PassThru | Format-List -property *

    Description
    ———–
    This command creates a global, read-only Variable that contains all processes on the system, and then it displays all properties of the Variable.

    The command uses the Set-Variable cmdlet to create the Variable. It uses the PassThru parameter to create an object representing the new Variable, and it uses the pipeline operator (|) to pass the object to the Format-List cmdlet. It uses the Property parameter of Format-List with a value of all (*) to display all properties of the newly created Variable.

    The value, “(Get-Process)”, is enclosed in parentheses to ensure that it is executed before being stored in the Variable. Otherwise, the Variable contains the words “Get-Process“.

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

    C:\PS># Set-Variable -Name counter -Visibility private

    C:\PS> New-Variable -Name counter -Visibility public -Value 26

    C:\PS> $counter
    26

    C:\PS> Get-Variable c*

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

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

    C:\PS> Get-Variable c*

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

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

    C:\PS> .\use-counter.ps1
    Commands completed successfully.

    Description
    ———–
    This command shows how to change the visibility of a Variable to “Private”. This Variable can be read and changed by scripts with the required permissions, but it is not visible to the user.

    The sample output shows the difference in the behavior of public and private Variables.

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

Alias, cmdlet, Set

Set-Alias

NAME
    Set-Alias

SYNOPSIS
    Creates or changes an Alias (alternate name) for a cmdlet or other command element in the current Windows PowerShell session.

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

DESCRIPTION
    The Set-Alias cmdlet creates or changes an Alias (alternate name) for a cmdlet or for a command element, such as a Function, a script, a file, or other executable. You can also use Set-Alias to reassign a current Alias to a new command, or to change any of the properties of an Alias, such as its description. Unless you add the Alias to the Windows PowerShell profile, the changes to an Alias are lost when you exit the session or close Windows PowerShell.

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

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

    -Force [<SwitchParameter>]
        Allows the cmdlet to set a read-only Alias. Use the Option parameter to create a read-only Alias. The Force parameter cannot set a constant Alias.

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

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

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

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

        Valid values are:

        — None: Sets no options. (default)

        — ReadOnly: The properties of the Alias cannot be changed, except by using the Force parameter. You can use Remove-Item to delete the Alias.

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

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

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

        To see the Options property of the Aliases, type “Get-Alias | Format-Table -property Name, Definition, Options -autosize”.

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

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

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

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

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

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

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

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

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

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

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

    <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 input to this cmdlet.

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

NOTES

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

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

        A cmdlet can have multiple Aliases, but an Alias can only be associated with one cmdlet at a time. If you use Set-Alias to associate the Alias with a different cmdlet, it is no longer associated with the original cmdlet.

        You can create an Alias for a cmdlet, but you cannot create an Alias for a command with parameters and values. For example, you can create an Alias for Set-Location, but you cannot create an Alias for “Set-Location C:\Windows\System32″. To create an Alias for a command, create a Function that includes the command, and then create an Alias to the Function.

        To save the Aliases from a session and use them in a different session, add the Set-Alias command to your Windows PowerShell profile. Profiles do not exist by default. To create a profile in the path stored in the $profile Variable, type “New-Item -type file -Force $profile”. To see the value of the $profile Variable, type “$profile”.

        You can also save your Aliases by using Export-Alias to copy the Aliases from the session to a file, and then use Import-Alias to add them to the Alias list for a new session.

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

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

    C:\PS>Set-Alias -Name list -Value Get-ChildItem

    Description
    ———–
    This command creates the Alias “list” for the Get-ChildItem cmdlet. After you create the Alias, you can use “list” in place of “Get-ChildItem” at the command line and in scripts.

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

    C:\PS>Set-Alias list Get-Location

    Description
    ———–
    This command associates the Alias “list” with the Get-Location cmdlet. If “list” is an Alias for another cmdlet, this command changes its association so that it now is the Alias only for Get-Location.

    This command uses the same format as the command in the previous example, but it omits the optional parameter names, -Name and -Value. When you omit parameter names, the values of those parameters must appear in the specified order in the command. In this case, the value of -Name (“list”) must be the first parameter and the value of -Value (“Get-Location“) must be the second parameter.

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

    C:\PS>Set-Alias scrub Remove-Item -Option readonly -PassThru | Format-List

    Description
    ———–
    This command associates the Alias “scrub” with the Remove-Item cmdlet. It uses the “ReadOnly” option to prevent the Alias from being deleted or assigned to another cmdlet.

    The PassThru parameter directs Windows PowerShell to pass an object that represents the new Alias through the pipeline to the Format-List cmdlet. If the PassThru parameter were omitted, there would be no output from this cmdlet to display (in a list or otherwise).

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

    C:\PS>Set-Alias np c:\windows\notepad.exe

    Description
    ———–
    This command associates the Alias, “np”, with the executable file for Notepad. After the command completes, to open Notepad from the Windows PowerShell command line, just type “np”.

    This example demonstrates that you can create Aliases for executable files and elements other than cmdlets.

    To make the command more generic, you can use the “Windir” Environment Variable (${env:windir}) to represent the C\Windows directory. The generic version of the command is “Set-Alias np ${env:windir}\notepad.exe”.

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

    C:\PS>function CD32 {Set-Location c:\windows\system32}

    C:\PS>Set-Alias go cd32

    Description
    ———–
    These commands show how to assign an Alias to a command with parameters, or even to a pipeline of many commands.

    You can create an Alias for a cmdlet, but you cannot create an Alias for a command that consists of a cmdlet and its parameters. However, if you place the command in a Function or a script, then you can create a useful Function or script name and you can create one or more Aliases for the Function or script.

    In this example, the user wants to create an Alias for the command “Set-Location c:\windows\system32″, where “Set-Location” is a cmdlet and “C:\Windows\System32” is the value of the Path parameter.

    To do this, the first command creates a Function called “CD32” that contains the Set-Location command.

    The second command creates the Alias “go” for the CD32 Function. Then, to run the Set-Location command, the user can type either “CD32” or “go”.

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

cmdlet, Content, Set

Set-Content

NAME
    Set-Content

SYNOPSIS
    Writes or replaces the content in an item with new content.

SYNTAX
    Set-Content [-LiteralPath] <string[]> [-Value] <Object[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

    Set-Content [-Path] <string[]> [-Value] <Object[]> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Set-Content cmdlet is a string-processing cmdlet that writes or replaces the content in the specified item, such as a file. Whereas the Add-Content cmdlet appends content to a file, Set-Content replaces the existing content. You can type the content in the command or send content through the pipeline to Set-Content.

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

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

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

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

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

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

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

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

    -Force [<SwitchParameter>]
        Allows the cmdlet to set the contents of a file, even if the file is read-only. Implementation varies from provider to provider. For more information, see about_providers. Even using the Force parameter, the cmdlet cannot override security restrictions.

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

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

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

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

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

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

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

    -Path <string[]>
        Specifies the path to the item that will receive the content. Wildcards are permitted.

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

    -Value <Object[]>
        Specifies the new content for the item.

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

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

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

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

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

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

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

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.Object
        You can pipe an object that contains the new value for the item to Set-Content.

OUTPUTS
    None or System.String
        When you use the Passthru parameter, Set-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output.

NOTES

        You can also refer to Set-Content by its built-in Alias, “sc”. For more information, see about_aliases.

        Set-Content is designed for string processing. If you pipe non-string objects to Set-Content, it converts the object to a string before writing it. To write objects to files, use Out-File.

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

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

    C:\PS>Set-Content -Path C:\Test1\test*.txt -Value “Hello, World”

    Description
    ———–
    This command replaces the contents of all files in the Test1 directory that have names beginning with “test” with “Hello, World”. This example shows how to specify content by typing it in the command.

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

    C:\PS>Get-Date | Set-Content C:\Test1\date.csv

    Description
    ———–
    This command creates a comma-separated Variable-length (csv) file that contains only the current date and time. It uses the Get-Date cmdlet to get the current system date and time. The pipeline operator passes the result to Set-Content, which creates the file and writes the content.

    If the Test1 directory does not exist, the command fails, but if the file does not exist, the command will create it.

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

    C:\PS>(Get-Content Notice.txt) | ForEach-Object {$_ -replace “Warning”, “Caution”} | Set-Content Notice.txt

    Description
    ———–
    This command replaces all instances of “Warning” with “Caution” in the Notice.txt file.

    It uses the Get-Content cmdlet to get the content of Notice.txt. The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in Get-Content. The expression uses the “$_” symbol to refer to the current item and the Replace parameter to specify the text to be replaced.

    Another pipeline operator sends the changed content to Set-Content which replaces the text in Notice.txt with the new content.

    The parentheses around the Get-Content command ensure that the Get operation is complete before the Set operation begins. Without them, the command will fail because the two Functions will be trying to access the same file.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113392
    about_providers
    Add-Content
    Get-Content
    Clear-Content

cmdlet, Item, Set

Set-Item

NAME
    Set-Item

SYNOPSIS
    Changes the value of an item to the value specified in the command.

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

    Set-Item [-Path] <string[]> [[-Value] <Object>] [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The Set-Item cmdlet changes the value of an item, such as a Variable or Registry key, to the value specified in the command.

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

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

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

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

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

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

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

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

    -Force [<SwitchParameter>]
        Allows the cmdlet to set items that cannot otherwise be changed, such as read-only Alias or Variables. The cmdlet cannot change constant Aliases or Variables. Implementation varies from provider to provider. For more information, see about_providers. Even using the Force parameter, the cmdlet cannot override security restrictions.

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

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

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

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

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

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

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

    -Path <string[]>
        Specifies a path to the location of the new items. Wildcards are permitted.

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

    -Value <Object>
        Specifies a new value for the item.

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

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

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

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

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

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

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

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.Object
        You can pipe an object that represents the new value of the item to Set-Item.

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

NOTES

        You can also refer to Set-Item by its built-in Alias, “si”. For more information, see about_aliases.

        The Set-Item cmdlet is not supported by the Windows PowerShell FileSystem provider. To change the values of items in the file system, use Set-Content.

        In the Registry drives, HKLM: and HKCU:, Set-Item changes the data in the (Default) value of a Registry key. To create and change the names of Registry keys, use New-Item and Rename-Item. To change the names and data in Registry values, use New-ItemProperty, Set-ItemProperty, and Rename-ItemProperty.

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

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

    C:\PS>Set-Item -Path Alias:np -Value c:\windows\notepad.exe

    Description
    ———–
    This command creates an Alias of “np” for Notepad.

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

    C:\PS>Set-Item -Path env:UserRole -Value Administrator

    Description
    ———–
    This command uses the Set-Item cmdlet to change the value of the “UserRole” Environment Variable to “Administrator”.

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

    C:\PS>Set-Item -Path Function:prompt -Value {‘PS ‘+ $(Get-Date -format t) + ” ” + $(Get-Location) + ‘> ‘}

    Description
    ———–
    This command uses the Set-Item cmdlet to change the “prompt” Function so that it displays the time before the path.

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

    C:\PS>Set-Item -Path Function:prompt -options “AllScope,ReadOnly”

    Description
    ———–
    This command sets the AllScope and ReadOnly options for the “prompt” Function. This command uses the Options dynamic parameter of the Set-Item cmdlet. The Options parameter is available in Set-Item only when you use it with the Alias or Function provider.

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

cmdlet, ItemProperty, Set

Set-ItemProperty

NAME
    Set-ItemProperty

SYNOPSIS
    Creates or changes the value of a property of an item.

SYNTAX
    Set-ItemProperty [-LiteralPath] <string[]> -InputObject <psobject> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

    Set-ItemProperty [-Path] <string[]> -InputObject <psobject> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

    Set-ItemProperty [-LiteralPath] <string[]> [-Name] <string> [-Value] <Object> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PassThru] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

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

DESCRIPTION
    The Set-ItemProperty cmdlet changes the value of the property of the specified item. You can use the cmdlet to establish or change the properties of items. For example, you can use Set-ItemProperty to set the value of the IsReadOnly property of a file object to true.

    You also use Set-ItemProperty to create and change Registry values and data. For example, you can add a new Registry entry to a key and establish or change its value.

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

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

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

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

    -Exclude <string[]>
        Specifies those items upon which the cmdlet is not to act, and includes all others.

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

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

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

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

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

    -Include <string[]>
        Specifies only those items upon which the cmdlet will act, excluding all others.

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

    -InputObject <psobject>
        Specifies the object that has the properties that you want to change. Enter a Variable that contains the object or a command that gets the object.

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

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

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

    -Name <string>
        Specifies the name of the property.

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

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

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

    -Path <string[]>
        Specifies the path to the items with the property to be set.

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

    -Value <Object>
        Specifies the value of the property.

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

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

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

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

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

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

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

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.Management.Automation.PSObject
        You can pipe objects to Set-ItemProperty.

OUTPUTS
    None or System.Management.Automation.PSCustomObject
        When you use the PassThru parameter, Set-ItemProperty generates a PSCustomObject object that represents the item that was changed and its new property value. Otherwise, this cmdlet does not generate any output.

NOTES

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

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

    C:\PS>Set-Itemproperty -Path c:\GroupFiles\final.doc -Name IsReadOnly -Value $true

    Description
    ———–
    This command sets the value of the IsReadOnly property of the final.doc file to true.

    The command uses the Set-ItemProperty cmdlet to change the value of the property of the final.doc file. It uses the Path parameter to specify the file. It uses the Name parameter to specify the name of the property and the Value parameter to specify the new value.

    The $true automatic Variable represents a value of TRUE. For more information, see about_Automatic_Variables.

    The file is a System.IO.FileInfo object and IsReadOnly is just one of its properties. To see all of the properties and methods of a FileInfo object, pipe the file to the Get-Member cmdlet. For example, “final.doc | Get-Member“.

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

    C:\PS>Set-Itemproperty -Path HKLM:\Software\MyCompany -Name NoOfEmployees -Value 823

    C:\PS>Get-Itemproperty -Path HKLM:\Software\MyCompany

    PSPath        : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany
    PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software
    PSChildName : mycompany
    PSDrive     : HKLM
    PSProvider    : Microsoft.PowerShell.Core\Registry
    NoOfLocations : 2
    NoOfEmployees : 823

    C:\PS>Set-Itemproperty -Path HKLM:\Software\MyCompany -Name NoOfEmployees -Value 824
    C:\PS>Get-Itemproperty -Path HKLM:\Software\MyCompany

    PSPath        : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany
    PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software
    PSChildName : mycompany
    PSDrive     : HKLM
    PSProvider    : Microsoft.PowerShell.Core\Registry
    NoOfLocations : 2
    NoOfEmployees : 824

    Description
    ———–
    This example shows how to use Set-ItemProperty to create a new Registry entry and to assign a value to the entry. It creates the NoOfEmployees entry in the MyCompany key in HKLM\Software key and sets its value to 823.

    Because Registry entries are considered to be properties of the Registry keys (which are items), you use Set-ItemProperty to create Registry entries, and to establish and change their values.

    The first command uses the Set-ItemProperty cmdlet to create the Registry entry. It uses the Path parameter to specify the path to the HKLM: drive and the Software\MyCompany key. It uses the Name parameter to specify the entry name and the Value parameter to specify a value.

    The second command uses the Get-ItemProperty cmdlet to see the new Registry entry. If you use the Get-Item or Get-ChildItem cmdlets, the entries do not appear because they are properties of a key, not items or child items.

    The third command changes the value of the NoOfEmployees entry to 824.

    You can also use the New-ItemProperty cmdlet to create the Registry entry and its value and then use Set-ItemProperty to change the value.

    For more information about the HKLM: drive, type “Get-Help Get-PSDrive“. For more information about using Windows PowerShell to manage the Registry, type “Get-Help Registry“.

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

    C:\PS>Get-ChildItem weekly.txt | Set-Itemproperty -Name IsReadOnly -Value $true

    Description
    ———–
    These commands show how to use a pipeline operator (|) to send an item to Set-ItemProperty.

    The first part of the command uses the Get-ChildItem cmdlet to get an object that represents the Weekly.txt file. The command uses a pipeline operator to send the file object to Set-ItemProperty. The Set-ItemProperty command uses the Name and Value parameters to specify the property and its new value.

    This command is equivalent to using the InputObject parameter to specify the object that Get-ChildItem gets.

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

cmdlet, New, Variable

New-Variable

NAME
    New-Variable

SYNOPSIS
    Creates a new Variable.

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

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

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

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

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

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

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

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

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

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

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

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

        Valid values are:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

        Valid values are:

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

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

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

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

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

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

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

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

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

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

NOTES

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

    C:\PS>New-Variable days

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

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

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

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

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

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

    New-Variable -Name max -Value 1024

    New-Variable -Name max -Value 1024 -Force

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

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

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

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

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

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

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

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

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

    #Effect of private Variable in a module.

    C:\PS> Get-Variable c*

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

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

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

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

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

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

Alias, cmdlet, New

New-Alias

NAME
    New-Alias

SYNOPSIS
    Creates a new Alias.

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

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

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

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

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

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

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

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

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

        — None: Sets no options. (default)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    <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 input to this cmdlet.

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

NOTES

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

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

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

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

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

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

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

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

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

cmdlet, Item, New

New-Item

NAME
    New-Item

SYNOPSIS
    Creates a new item.

SYNTAX
    New-Item [-Path] <string[]> [-Credential <PSCredential>] [-Force] [-ItemType <string>] [-Value <Object>] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

    New-Item -Name <string> [[-Path] <string[]>] [-Credential <PSCredential>] [-Force] [-ItemType <string>] [-Value <Object>] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The New-Item cmdlet creates a new item and sets its value. The types of items that can be created depend upon the location of the item. For example, in the file system, New-Item is used to create files and folders. In the Registry, New-Item creates Registry keys and entries.

    New-Item can also set the value of the items that it creates. For example, when creating a new file, New-Item can add initial content to the file.

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

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

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

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

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

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

    -ItemType <string>
        Specifies the provider-specified type of the new item.

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

    -Name <string>
        Specifies the name of the new item. You can use this parameter to specify the name of the new item, or include the name in the value of the Path parameter.

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

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

        You can specify the name of the new item in the Name parameter, or include it in the Path parameter.

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

    -Value <Object>
        Specifies the value of the new item. You can also pipe a value to New-Item.

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

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

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

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

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

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

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

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.Object
        You can pipe a value for the new item to the New-Item cmdlet.

OUTPUTS
    System.Object
        New-Item returns the item that it creates.

NOTES

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

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

    C:\PS>New-Item -Path . -name testfile1.txt -type “file” -Value “This is a text string.”

    Description
    ———–
    This command creates a text file named testfile1.txt in the current directory. The dot (.) in the value of the Path parameter indicates the current directory. The quoted text that follows the Value parameter is added to the file as content.

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

    C:\PS>New-Item -Path c:\ -name logfiles -type directory

    Description
    ———–
    This command creates a directory named Logfiles in the C: drive. The Type parameter specifies that the new item is a directory, not a file or other file system object.

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

    C:\PS>New-Item -Path $profile -type file -Force

    Description
    ———–
    This command creates a Windows PowerShell profile in the path that is specified by the $profile Variable.

    You can use profiles to customize Windows PowerShell. $Profile is an automatic (built-in) Variable that stores the path and file name of the CurrentUser/CurrentHost profile. By default, the profile does not exist, even though Windows PowerShell stores a path and file name for it.

    In this command, the $profile Variable represents the path to the file. The Type parameter (or InfoType) specifies that the command creates a file. The Force parameter lets you create a file in the profile path, even when the directories in the path do not exist (Windows PowerShell creates them).

    After you use this command to create a profile, you can enter Aliases, Functions, and scripts in the profile to customize your shell.

    For more information, see about_Automatic_Variables and about_profiles.

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

    C:\PS>New-Item -type directory -Path c:\ps-test\scripts

    Description
    ———–
    This command creates a new Scripts directory in the C:\PS-Test directory.

    The name of the new directory item, Scripts, is included in the value of the Path parameter, instead of being specified in the value of the Name parameter. As indicated by the syntax, either command form is valid.

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

cmdlet, ItemProperty, New

New-ItemProperty

NAME
    New-ItemProperty

SYNOPSIS
    Creates a new property for an item and sets its value. For example, you can use New-ItemProperty to create and change Registry values and data, which are properties of a Registry key.

SYNTAX
    New-ItemProperty [-LiteralPath] <string[]> [-Name] <string> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PropertyType <string>] [-Value <Object>] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

    New-ItemProperty [-Path] <string[]> [-Name] <string> [-Credential <PSCredential>] [-Exclude <string[]>] [-Filter <string>] [-Force] [-Include <string[]>] [-PropertyType <string>] [-Value <Object>] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
    The New-ItemProperty cmdlet creates a new property for a specified item and sets its value. Typically, this cmdlet is used to create new Registry values, because Registry values are properties of a Registry key item.

    This cmdlet does not add properties to an object. To add a property to an instance of an object, use the Add-Member cmdlet. To add a property to all objects of a particular type, edit the Types.ps1xml file.

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

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

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

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

    -Exclude <string[]>
        Omits the specified items. Wildcards are permitted.

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

    -Filter <string>
        Specifies a filter in the provider’s format or language. The value of this parameter qualifies the Path parameter.

        The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects rather than having Windows PowerShell filter the objects after they are retrieved.

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

    -Force [<SwitchParameter>]
        Allows the cmdlet to create a property on an object that cannot otherwise be accessed by the user. Implementation varies from provider to provider. For more information, see about_providers.

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

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

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

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

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

    -Name <string>
        Specifies a name for the new property. If the property is a Registry entry, this parameter specifies the name of the entry.

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

    -Path <string[]>
        Specifies the path to the item. This parameter identifies the item to which the new property will be added.

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

    -PropertyType <string>
        Specifies the type of property that will be added.

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

    -Value <Object>
        Specifies the property value. If the property is a Registry entry, this parameter specifies the value of the entry.

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

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

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

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

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

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

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

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    None
        You cannot pipe input to New-ItemProperty.

OUTPUTS
    System.Management.Automation.PSCustomObject
        New-ItemProperty returns a custom object that contains the new property.

NOTES

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

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

    C:\PS>New-Itemproperty -Path HKLM:\Software\MyCompany -Name NoOfEmployees -Value 822

    C:\PS> Get-Itemproperty hklm:\software\mycompany

    PSPath        : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software\mycompany
    PSParentPath : Microsoft.PowerShell.Core\Registry::HKEY_LOCAL_MACHINE\software
    PSChildName : mycompany
    PSDrive     : HKLM
    PSProvider    : Microsoft.PowerShell.Core\Registry
    NoOfLocations : 2
    NoOfEmployees : 822

    Description
    ———–
    This command adds a new Registry entry, NoOfEmployees, to the MyCompany key of the HKLM:\Software hive.

    The first command uses the Path parameter to specify the path to the MyCompany Registry key. It uses the Name parameter to specify a name for the entry and the Value parameter to specify its value.

    The second command uses the Get-ItemProperty cmdlet to see the new Registry entry.

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

    C:\PS>Get-Item -Path HKLM:\Software\MyCompany | New-Itemproperty -Name NoOfLocations -Value 3

    Description
    ———–
    This command adds a new Registry entry to a Registry key. To specify the key, it uses a pipeline operator (|) to send an object representing the key to the New-ItemProperty cmdlet.

    The first part of the command uses the Get-Item cmdlet to get the MyCompany Registry key. The pipeline operator (|) sends the results of the command to the New-ItemProperty cmdlet, which adds the new Registry entry, NoOfLocations, and its value, 3, to the MyCompany key.

    This command works because the parameter-binding feature of Windows PowerShell associates the path of the RegistryKey object that Get-Item returns with the LiteralPath parameter of New-ItemProperty. For more information, see about_pipelines.

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

Add, cmdlet, Member

Add-Member

NAME
    Add-Member

SYNOPSIS
    Adds a user-defined custom member to an instance of a Windows PowerShell object.

SYNTAX
    Add-Member [-MemberType] {AliasProperty | CodeProperty | Property | NoteProperty | ScriptProperty | Properties | PropertySet | Method | CodeMethod | ScriptMethod | Methods | ParameterizedProperty | MemberSet | Event | All} [-Name] <string> -InputObject <psobject> [[-Value] <Object>] [[-SecondValue] <Object>] [-Force] [-PassThru] [<CommonParameters>]

DESCRIPTION
    The Add-Member cmdlet adds a user-defined custom member to an instance of a Windows PowerShell object. It lets you add the following types of members: AliasProperty, CodeProperty, NoteProperty, ScriptProperty, PropertySet, CodeMethod, MemberSet, and ScriptMethod. You set the initial value of the member by using the Value parameter. In the case of AliasProperty, ScriptProperty, CodeProperty, and CodeMethod, you can supply additional information by using the SecondValue parameter.

    The additional members are added to the particular instance of the object that you pipe to Add-Member or specify using the InputObject parameter. The additional member is available only while that instance exists. You can use the Export-Clixml cmdlet to save the instance, including the additional members, to a file. The information stored in that file can be used by the Import-Clixml cmdlet to re-create the instance of the object.

PARAMETERS
    -Force [<SwitchParameter>]
        Adds a new member even if one with the same name already exists. Does not work for core members of a type.

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

    -InputObject <psobject>
        Specifies the object to which the new member is added. Enter a Variable that contains the objects, or type a command or expression that gets the objects.

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

    -MemberType <PSMemberTypes>
        Specifies the type of the member to add. This parameter is mandatory.

        The valid values for this parameter are:
        — AliasProperty: A property that defines a new name for an existing property.
        — CodeMethod: A method that references a static method of a Microsoft .NET Framework class.
        — CodeProperty: A property that references a static property of a .NET Framework class.
        — MemberSet: A predefined collection of properties and methods, such as PSBase, PSObject, and PSTypeNames.
        — Method: A method of the underlying .NET Framework object.
        — NoteProperty: A property with a static value.
        — ParameterizedProperty: A property that takes parameters and parameter values.
        — Property: A property of the underlying .NET Framework object.
        — PropertySet: A predefined collection of object properties.
        — ScriptMethod: A method whose value is the output of a script.
        — ScriptProperty: A property whose value is the output of a script.

        — All: Gets all member types.
        — Methods: Gets all types of methods of the object (e.g. method, codemethod, scriptmethod)
        — Properties: Gets all types of properties of the object (e.g. property, codeproperty, Aliasproperty, scriptproperty).

        Not all objects have every type of member. If you specify a member type that the object does not have, Windows PowerShell returns an error.

        The Event member type is not valid for Add-Member.

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

    -Name <string>
        Specifies the name of the member to be added.

        If you omit the “Name” parameter name, the value of the -Name parameter must be the second unnamed parameter value in the command. If you include the parameter name, the parameters can appear in any order.

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

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

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

    -SecondValue <Object>
        Specifies optional additional information about AliasProperty, ScriptProperty, CodeProperty, or CodeMethod members. If used when adding an AliasProperty, this parameter must be a data type. A conversion (cast) to the specified data type is added to the value of the AliasProperty. For example, if you add an AliasProperty that provides an alternate name for a string property, you can also specify a SecondValue parameter of System.Int32 to indicate that the value of that string property should be converted to an integer when accessed by using the corresponding AliasProperty.

        You can use the SecondValue parameter to specify an additional ScriptBlock when adding a ScriptProperty member. In that case, the first ScriptBlock, specified in the Value parameter, is used to get the value of a Variable. The second ScriptBlock, specified in the SecondValue parameter, is used to set the value of a Variable.

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

    -Value <Object>
        Specifies the initial value of the added member. If you add an AliasProperty, CodeProperty, or CodeMethod member, you can supply optional, additional information by using the SecondValue parameter.

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

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.Management.Automation.PSObject
        You can pipe any object type to Add-Member.

OUTPUTS
    None or System.Object
        When you use the PassThru parameter, Add-Member returns the newly-extended object. Otherwise, this cmdlet does not generate any output.

NOTES

        You can add members only to PSObject objects. To determine if an object is a PSObject object, use the “is” operator. For example, to test an object stored in the $obj Variable, type “$obj -is [PSObject]”.

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

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

    C:\PS>$a = (Get-ChildItem)[0]

    C:\PS> $a | Add-Member -MemberType noteproperty -Name Status -Value done

    C:\PS> $a | Get-Member -type noteproperty

     TypeName: System.IO.DirectoryInfo

    Name         MemberType Definition
    —-         ———- ———-
    PSChildName NoteProperty System.String PSChildName=Co
    PSDrive     NoteProperty System.Management.Automation
    PSIsContainer NoteProperty System.Boolean PSIsContainer
    PSParentPath NoteProperty System.String PSParentPath=M
    PSPath        NoteProperty System.String PSPath=Microso
    PSProvider    NoteProperty System.Management.Automation
    Status        NoteProperty System.String Status=done

    Description
    ———–
    These commands add the Status note property to a DirectoryInfo object returned by Get-ChildItem and assigns it a value of “done”.

    The first command gets the first object that Get-ChildItem returns (index 0).

    The second command adds the note property.

    The third command uses a pipeline operator (|) to send the updated object to the Get-Member cmdlet. The output shows that the property has been added.

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

    C:\PS>$a = (Get-ChildItem)[0]

    C:\PS> $a | Add-Member -MemberType Aliasproperty -Name FileLength -Value Length

    C:\PS> $a.filelength

    Description
    ———–
    These commands add the FileLength Alias property to a DirectoryInfo object returned by Get-ChildItem. The new property is an Alias for the Length property.

    The first command gets the first object that Get-ChildItem returns (index 0).

    The second command adds the Alias property.

    The third command returns the value of the new FileLength property.

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

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

    C:\PS> $a = $a | Add-Member -MemberType noteproperty -Name StringUse -Value Display -PassThru

    C:\PS> $a.StringUse

    Description
    ———–
    These commands add the StringUse a property to a string. Because the string is not a PSObject object, you must include the PassThru parameter in the command to save the extended string in the Variable. The last command in the example displays the new property.

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

    C:\PS>$a = “this is a string”

    C:\PS> $a = Add-Member -InputObject $a -MemberType scriptmethod -Name words `
    -Value {$this.split()} -PassThru

    C:\PS> $a.words()

    Description
    ———–
    These commands add a script method to a string object. The script method exposes the Split() method of the System.String .NET Framework Class Library class to make it convenient to return the individual words in a string by calling a method named “Words” on the string object. Note that the PassThru parameter is specified to force Add-Member to return the extended string object as output to be stored in the $a Variable.

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

    C:\PS>$event = Get-Eventlog -logname system -newest 1

    C:\PS> $event.TimeWritten | Get-Member

    C:\PS> Add-Member -InputObject $event -MemberType Aliasproperty -Name When `
    -Value TimeWritten -SecondValue System.String

    C:\PS> $event.When | Get-Member

    Description
    ———–
    These commands add an AliasProperty to an EventLogEntry object returned by the Get-EventLog cmdlets. The AliasProperty is named “When” and is an Alias for the TimeWritten property of the object. The SecondValue parameter is used to specify that the property value should be converted to type System.String when accessed by using the AliasProperty; the TimeWritten property is a DateTime object.

    The first command uses the Get-EventLog cmdlet to retrieve the most recent event from the System event log and stores it in the $event Variable.

    The second command accesses the TimeWritten property of that event and pipes it to the Get-Member cmdlet to demonstrate that the property is a DateTime type. Add-Member is then used to add an AliasProperty member to the instance of the EventLogEntry object stored in the $event Variable. The Name parameter is used to set the name of the new member to “When” and the Value parameter is used to specify that it is an Alias for the TimeWritten property. The SecondValue parameter is used to indicate that, when this new member is used, the value it returns should be cast from its original System.DateTime type to a System.String type.

    The third command accesses the new member and pipes it to the Get-Member cmdlet to confirm that it is of type System.String.

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

    C:\PS>function Copy-Property ($From, $To)

    {
     foreach ($p in Get-Member -InputObject $From -MemberType Property)
     {
         Add-Member -InputObject $To -MemberType NoteProperty -Name $p.Name
         -Value $From.$($p.Name) -Force

         $To.$($p.Name) = $From.$($p.Name)
     }
    }

    Description
    ———–
    This Function copies all of the properties of one object to another object.

    The first command in the Function declares the Function name and lists its parameters.

    The Foreach loop uses the Get-Member cmdlet to get each of the properties of the From object. The commands within the Foreach loop are performed in series on each of the properties.

    The Add-Member command adds the property of the From object to the To object as a NoteProperty. It uses the Force parameter to let the command add members with the same member name.

    The last command in the Function gives the new property the same name as the original property.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113280
    Get-Member
    Export-Clixml
    Import-Clixml