All posts by Adam

Disable-PSRemoting

NAME
    Disable-PSRemoting

SYNOPSIS
    Prevents the computer from receiving remote Windows PowerShell commands.

SYNTAX
    Disable-PSRemoting [-Force] [-Confirm] [-WhatIf] [<CommonParameters>]

DESCRIPTION
    The Disable-PSRemoting Function disables all session configurations on the local computer by adding a “deny all” entry to their security descriptors. This prevents the local computer from receiving remote commands.

    Disable-PSRemoting does not stop the WinRM service and it does not prevent users of the local computer from establishing sessions that connect to remote computers or sending commands to other computers.

    To re-enable the session configurations, use the Enable-PSRemoting or Enable-PSSessionConfiguration cmdlets.

    To run this Function on Windows Vista, Windows Server 2008, and later versions of Windows, you must open Windows PowerShell with the “Run as administrator” option.

PARAMETERS
    -Force [<SwitchParameter>]
        Suppresses all user prompts. By default, you are prompted to confirm each operation.

        Required?                    false
        Position?                    named
        Default value                False
        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
    None
        You cannot pipe input to this cmdlet.

OUTPUTS
    None
        This cmdlet does not return any object.

NOTES

        A session configuration is a group of settings that define the Environment for a session. The session configurations are located on the remote computer and are used by local and remote sessions that connect to the computer.

        Every session that connects to the computer must use one of the session configurations that are registered on the computer. This includes persistent sessions that you create by using New-PSSession or Enter-PSSession cmdlets, and the temporary sessions that Windows PowerShell creates when you use the ComputerName parameter of a cmdlet that uses WS-Management remoting technology, such as Invoke-Command. By denying access to all session configurations, you effectively prevent all users from establishing sessions that connect to the computer.

        Disable-PSRemoting is the equivalent of “Disable-PSSessionConfiguration -name *.

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

    C:\PS>disable-psremoting

    Description
    ———–
    This command disables all session configurations on the computer.

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

    C:\PS>disable-psremoting -force

    Description
    ———–
    This command disables all session configurations on the computer without prompting.

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

    C:\PS>disable-psremoting -force

    C:\PS> New-PSSession -computername localhost

    [localhost] Connecting to remote server failed with the following error
    message : Access is denied. For more information, see the about_remote_Troub
    leshooting Help topic.
        + CategoryInfo         : OpenError: (System.Manageme….RemoteRunspace:RemoteRunspace) [], PSRemotingTransportException
        + FullyQualifiedErrorId : PSSessionOpenFailed

    C:\PS> New-PSSession -computername Server01

     Id Name     ComputerName    State    Configuration         Availability
     — —-     ————    —–    ————-         ————
     1 Session1 Server01…     Opened Microsoft.PowerShell     Available

    C:\PS> Enable-PSSessionConfiguration -name * -force

    C:\PS> New-PSSession -computername localhost

     Id Name     ComputerName    State    Configuration         Availability
     — —-     ————    —–    ————-         ————
     1 Session1 localhost     Opened Microsoft.PowerShell     Available

    Description
    ———–
    This example shows the effect of using Disable-PSRemoting.

    The first command uses Disable-PSRemoting to disable all registered session configurations on the local computer.

    The second command uses the New-PSSession to create a remote session to the local computer (also known as a “loopback”). Because the session configurations that session requires are disabled, the command fails.

    The third command uses the New-PSSession cmdlet to create a session from the local computer to the Server01 remote computer. This command, which uses the session configurations on the remote computer, succeeds.

    The fourth command uses the Enable-PSSessionConfiguration cmdlet to re-enable all of the session configurations on the local computer. The command uses a value of * (all) in the Name parameter.

    The fifth command attempts again to establish a loopback session by using the New-PSSession cmdlet. This time the command succeeds, because the session configuration that requires are enabled.

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

    C:\PS>disable-psremoting -force

    C:\PS> Get-PSSessionConfiguration | Format-Table -property name, permission -auto

    Name                 Permission
    —-                 ———-
    microsoft.powershell Everyone AccessDenied, BUILTIN\Administrators AccessAllowed
    microsoft.powershell32 Everyone AccessDenied, BUILTIN\Administrators AccessAllowed

    C:\PS> Enable-PSRemoting -force
    WinRM already is set up to receive requests on this machine.
    WinRM already is set up for remote management on this machine.

    C:\PS>> Get-PSSessionConfiguration | ft name, Permission -auto

    Name                 Permission
    —-                 ———-
    microsoft.powershell BUILTIN\Administrators AccessAllowed
    microsoft.powershell32 BUILTIN\Administrators AccessAllowed

    Description
    ———–
    This example shows the effect on the session configurations of using Disable-PSRemoting and Enable-PSRemoting.

    The first command uses the Disable-PSRemoting Function to disable all registered session configurations. The force parameter suppresses all user prompts.

    The second command uses the Get-PSSessionConfiguration cmdlet to display the registered session configurations on the computer. The command uses a pipeline operator to send the results to a Format-Table command, which displays only the Name and Permission properties of the configurations in a table.

    The resulting table shows that everyone is denied permission to the configurations.

    The third command uses the Enable-PSRemoting cmdlet to re-enable all of the session configurations on the computer. You can also use an “Enable-PSSessionConfiguration -name *” command. The command uses the Force parameter to suppress all user prompts and to restart the WinRM service without prompting.

    The fourth command uses Get-PSSessionConfiguration and Format-Table to display the names and permissions of the session configurations. The results show that members of the Administrators group now have access to the session configurations.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=144298
    Enable-PSRemoting
    Disable-PSSessionConfiguration
    Get-PSSessionConfiguration
    Register-PSSessionConfiguration
    Set-PSSessionConfiguration
    Unregister-PSSessionConfiguration
    WS-Management Provider

Certificate

PROVIDER NAME
    Certificate

DRIVES
    Cert:

SYNOPSIS
    Provides access to X.509 Certificate stores and Certificates from within Windows PowerShell.

DESCRIPTION
    The Windows PowerShell security strategy supports the use of Authenticode signatures to sign scripts using X.509-encoded digital public key Certificates. The signing features of Windows PowerShell are not intended to be complete, but they enable users to sign scripts and enable Windows PowerShell to recognize signed and unsigned scripts and to determine whether the scripts originate on the Internet.

    The Windows PowerShell Certificate provider lets you navigate the Certificate namespace and view the Certificate stores and Certificates. It also lets you copy, move, and delete Certificates and Certificate stores, and it lets you open the Certificates snap-in for the Microsoft Management Console (MMC).

    The Certificate provider exposes the Certificate namespace as the Cert: drive in Windows PowerShell. The Cert: drive has the following three levels:

    — Store locations (Microsoft.PowerShell.Commands.X509StoreLocation), which are high-level containers that group the Certificates for the current user and for all users. Each system has a CurrentUser and LocalMachine (all users) store location.

    — Certificates stores (System.Security.Cryptography.X509Certificates.X509Store), which are physical stores in which Certificates are saved and managed.

    — X.509 Certificates (System.Security.Cryptography.X509Certificates.X509Certificate2), each of which represent an X.509 Certificate on the computer. Certificates are identified by their thumbprints.

    The Windows PowerShell Certificate provider supports the Set-Location, Get-Location, Get-Item, Get-ChildItem, and Invoke-Item cmdlets.

    In addition, the Windows PowerShell Security snap-in (Microsoft.PowerShell.Security), which includes the Certificate provider, also includes snap-ins to get and set Authenticode signatures and to get Certificates. For a list of cmdlets in the Security snap-in, type “Get-Command -module *security”.

CAPABILITIES

TASKS
    TASK: Navigating the Cert: Drive

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

        This command uses the Set-Location cmdlet to change the current location to the Cert: drive.

        Set-Location cert:

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

        This command uses the Set-Location command to change the current location to the Root Certificate store in the LocalMachine store location. Use a backslash (\) or a forward slash (/) to indicate a level of the Cert: drive.

        Set-Location -path LocalMachine\Root

        If you are not in the Cert: drive, begin the path with the drive name.

    TASK: Displaying the Contents of the Cert: Drive

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

        This command uses the Get-ChildItem cmdlet to display the Certificate stores in the CurrentUser Certificate store location.

        Get-ChildItem -path cert:\CurrentUser

        If you are in the Cert: drive, you can omit the drive name.
        ————————– EXAMPLE 2 ————————–

        This command uses the Get-ChildItem cmdlet to display the Certificates in the My Certificate store.

        Get-ChildItem -path cert:\CurrentUser\My

        If you are in the Cert: drive, you can omit the drive name.
        ————————– EXAMPLE 3 ————————–

        This command uses the Get-Item cmdlet to get the “My” Certificate store and the Property parameter of Format-List with a wildcard character (*) to display all of the properties of the store.

        Get-Item -path cert:\CurrentUser\My | Format-List *

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

        This command gets a Certificate and displays all of its properties. It uses the Get-ChildItem cmdlet to get the Certificate and the Property parameter of Format-List with a wildcard character (*) to display all of the properties of the Certificate.

        The Certificate is identified by its thumbprint.

        Get-ChildItem -path cert:\CurrentUser\my\6B8223358119BB08840DEE50FD8AF9EA776CE66B | Format-List -property *

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

        This command uses the Get-ChildItem cmdlet to get all of the Certificates on the computer and its CodeSigningCert dynamic parameter to get only the Certificates that have code-signing authority.

        Get-ChildItem -path * -codesigningcert -recurse

    TASK: Opening the Certificates MMC Snap-in

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

        This command opens the Certificates MMC snap-in to manage the specified Certificate.

        invoke item cert:\CurrentUser\my\6B8223358119BB08840DEE50FD8AF9EA776CE66B

DYNAMIC PARAMETERS
    -CodeSigningCert <System.Management.Automation.SwitchParameter>
        Gets only those Certificates with code-signing authority.

        Cmdlets Supported: Get-Item, Get-ChildItem

NOTES

RELATED LINKS
    about_providers
    about_Signing
    Get-AuthenticodeSignature
    Set-AuthenticodeSignature
    Get-PfxCertificate

Variable

PROVIDER NAME
    Variable

DRIVES
    Variable:

SYNOPSIS
    Provides access to the Windows PowerShell Variables and to their values.

DESCRIPTION
    The Windows PowerShell Variable provider lets you get, add, change, clear, and delete Windows PowerShell Variables in the current console.

    The Windows PowerShell Variable provider supports the Variables that Windows PowerShell creates, including the automatic Variables, the preference Variables, and the Variables that you create.

    The Variable provider is a flat namespace that contains only the Variable objects. The Variables have no child items.

    Most of the Variables are instances of the System.Management.Automation.PSVariable class. However, there are some variations. For example, the “?” Variable is a member of the QuestionMarkVariable class, and the “MaximumVariableCount” Variable is a member of the SessionStateCapacityVariable class.

    The Variable provider exposes its data store in the Variable: drive. To work with Variables, you can change your location to the Variable: drive (“Set-Location Variable:”), or you can work from any other Windows PowerShell drive. To reference a Variable from another location, use the drive name (Variable:) in the path.

    Windows PowerShell includes a set of cmdlets designed especially to view and to change Variables:

    — Get-Variable
    — New-Variable
    — Set-Variable
    — Remove-Variable
    — Clear-Variable

    When you use these cmdlets, you do not need to specify the Variable: drive in the name.

    The Variable provider supports all of the cmdlets whose names contain the Item noun (the Item cmdlets), except for Invoke-Item. The Variable provider supports the Get-Content and Set-Content cmdlets. However, it does not support the cmdlets whose names contain the ItemProperty noun (the ItemProperty cmdlets), and it does not support the Filter parameter in any cmdlet.

    You can also use the Windows PowerShell expression parser to create, view, and change the values of Variables without using the cmdlets. When working with Variables directly, use a dollar sign ($) to identify the name as a Variable and the assignment operator (=) to establish and change its value. For example, “$p = Get-Process” creates the “p” Variable and stores the results of a “Get-Process” command in it.

    All changes to the Variables affect the current session only. To save the changes, add the changes to the Windows PowerShell profile, or use Export-Console to save the current console.

CAPABILITIES

TASKS
    TASK: Getting to the Variable: Drive

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

        This command changes the current location to the Variable: drive. You can use this command from any drive in Windows PowerShell. To return to a file system drive, type the drive name. For example, type “Set-Location c:”.

        Set-Location Variable:

    TASK: Displaying the Value of Variables

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

        This command gets the list of all the Variables and their values in the current session. You can use this command from any Windows PowerShell drive.

        Get-ChildItem -path Variable:

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

        This command gets the Variables with names that begin with “max”. You can use this command from any Windows PowerShell drive.

        Get-ChildItem -path Variable:max*

        If you are in the Variable: drive, you can omit the drive name from the path.
        ————————– EXAMPLE 3 ————————–

        This command gets the value of the WhatIfPreference Variable by typing it at the command line.

        The name of the Variable is preceded by a dollar sign ($) to indicate that it is a Variable. The Variable: drive name is not specified.

        $WhatIfPreference

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

        This command uses the LiteralPath parameter of Get-ChildItem to get the value of the “?” Variable from within the Variable: drive. Get-ChildItem does not attempt to resolve any wildcards in the values of the LiteralPath parameter.

        Get-ChildItem -literalpath ?

        To display the value of a Variable with a special character name without a cmdlet, type a dollar sign ($) and the Variable name. For example, to display the value of the “?” Variable, type “$?”.
        ————————– EXAMPLE 5 ————————–

        This command gets the Variables that have the values of “ReadOnly” or “Constant” for their Options property.

        Get-ChildItem -path Variable: | Where-Object {$_.options -match “Constant” -or $_.options -match “ReadOnly”} | Format-List -property name, value, options

    TASK: Creating a New Variable

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

        This command creates the “services” Variable and stores the results of a Get-Service command in it. Because the current location is in the Variable: drive, the value of the Path parameter is a dot (.), which represents the current location.

        The parentheses around the Get-Service command ensure that the command is executed before the Variable is created. Without the parentheses, the value of the new Variable is a “Get-Service” string.

        New-Item -path . -name services -value (Get-Service)

        If you are not in the Variable: drive, include the Variable: drive name in the path.
        ————————– EXAMPLE 2 ————————–

        This command creates a “services” Variable and stores the result of a Get-Service command in it.

        The command uses a dollar sign ($) to indicate a Variable and the assignment operator (=) to assign the result of the Get-Service command to the newly created Variable.

        $services = Get-Service

        To create a Variable without a value, omit the assignment operator.

    TASK: Displaying the Properties and Methods of Variables

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

        This command uses the Get-Item cmdlet to get all Variables. The pipeline operator (|) sends the results to the Get-Member cmdlet, which displays the methods and properties of the object.

        Get-Item -path Variable:* | Get-Member

        When you pipe a collection of objects (such as the collection of Variables in the Variable: drive) to Get-Member, Get-Member evaluates each object in the collection separately and returns information about each of the object types that it finds.

        To get information about the collection of objects in the Variable: drive, use the InputObject parameter of Get-Member. For example, “Get-Member -inputobject (Get-Item Variable:*)”. When you use InputObject, Get-Member evaluates the collection, not the objects in the collection.
        ————————– EXAMPLE 2 ————————–

        This command lists the values of the properties of the “home” Variable. It uses the Get-Item cmdlet to get an object that represents the “home” Variable. The pipeline operator (|) sends the results to the Format-List command. The Format-List command uses the Property parameter with a wildcard character (*) to format and to display the values of all of the properties of the “home” Variable.

        Get-Item Variable:home | Format-List -property *

    TASK: Changing the Properties of a Variable

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

        This command uses the Rename-Item cmdlet to change the name of the “a” Variable to “processes”.

        Rename-Item -path Variable:a -newname processes

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

        This command uses the Set-Item cmdlet to change the value of the ErrorActionPreference Variable to “Stop”.

        Set-Item -path Variable:ErrorActionPreference -value Stop

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

        This command changes the value of the ErrorActionPreference Variable to “Stop”.

        It uses a dollar sign ($) to indicate a Variable and the assignment operator (=) to assign the value.

        $ErrorActionPreference = Stop

    TASK: Copying a Variable

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

        This command uses the Copy-Item cmdlet to copy the “processes” Variable to “old_processes”. This creates a new Variable named “old_processes” that has the same value as the “processes” Variable.

        Copy-Item -path Variable:processes -destination Variable:old_processes

        If the command is issued from within the Variable: drive, you can omit the drive name from the value of the Path parameter.
        ————————– EXAMPLE 2 ————————–

        This command copies the “processes” Variable to “old_processes” without using a cmdlet. It uses the dollar sign ($) to indicate Variables and the assignment operator to assign the value of $processes to old_processes.

        $old_processes = $processes

    TASK: Deleting a Variable

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

        This command deletes the “serv” Variable from the current session. You can use this command in any Windows PowerShell drive.

        Remove-Variable -path Variable:serv

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

        This command deletes all Variables from the current session except for the Variables whose Options property has a value of Constant. Without the Force parameter, the command does not delete Variables whose Options property has a value of ReadOnly.

        Remove-Item Variable:* -force

    TASK: Setting the Value of a Variable to NULL

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

        This command uses the Clear-Item cmdlet to change the value of the “processes” Variable to NULL.

        Clear-Item -path Variable:processes

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

        This command clears the value of the “processes” Variable by assigning a null value to it. It uses the $null automatic Variable to represent the NULL value.

        $processes = $null

DYNAMIC PARAMETERS

NOTES
    The Variable provider does not support any dynamic parameters.

RELATED LINKS
    about_Variables
    about_Automatic_Variables
    about_providers

Registry

PROVIDER NAME
    Registry

DRIVES
    HKLM:, HKCU:

SYNOPSIS
    Provides access to the system Registry keys and values from Windows PowerShell.

DESCRIPTION
    The Windows PowerShell Registry provider lets you get, add, change, clear, and delete Registry keys and values in Windows PowerShell.

    Registry keys are represented as instances of the Microsoft.Win32.RegistryKey class. Registry values are represented as instances of the PSCustomObject class.

    The Registry provider lets you access a hierarchical namespace that consists of Registry keys and subkeys. Registry values and data are not components of that hierarchy. Instead, they are properties of each of the keys.

    The Registry provider supports all the cmdlets that contain the Item noun (the Item cmdlets), such as Get-Item, Copy-Item, and Rename Item. Use the Item cmdlets when you work with Registry keys and subkeys. The Registry provider also supports the cmdlets that contain the ItemProperty noun (the ItemProperty cmdlets). Use the ItemProperty cmdlets when you work with Registry values and data. You cannot use the cmdlets that contain the Content noun (the Content cmdlets) with the Registry provider.

    Each Registry key is protected by a security descriptor. You can use Get-Acl to view the security descriptor of a key.

CAPABILITIES
    ShouldProcess

TASKS
    TASK: Navigating the Registry

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

        This command sets the current location to the HKEY_LOCAL_MACHINE\Software Registry key:

        Set-Location hklm:\software

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

        This command displays the current location:

        Get-Location

    TASK: Managing Registry Keys

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

        This command displays information about each immediate subkey of the HKEY_LOCAL_MACHINE\Software Registry key:

        Get-ChildItem -path hklm:\software

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

        This command creates the TestNew subkey under the HKCU:\Environment subkey:

        New-Item -path hkcu:\Environment\TestNew

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

        This command removes the TestNew subkey of the HKEY_CURRENT_USER\Environment key:

        Remove-Item -path hkcu:\Environment\TestNew

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

        This command copies the TestNew key to the TestCopy subkey:

        Copy-Item -path hkcu:\Environment\TestNew hkcu:\Environment\TestNew\TestCopy

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

        This command displays information about all the subkeys of the HKEY_LOCAL_MACHINE\Software Registry key:

        Get-ChildItem -path hklm:\Software -recurse

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

        This command moves the HKEY_CURRENT_USER\Environment\testnewcopy Registry key, its properties, and all its subkeys and their properties to HKEY_CURRENT_USER\Environment\testnew:

        Move-Item -path hkcu:\environment\testnewcopy `
        -destination hkcu:\environment\testnew

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

        This command renames the HKEY_CURRENT_USER\Environment\testnew Registry key to HKEY_CURRENT_USER\Environment\test:

        Rename-Item -path hkcu:\environment\testnew\ -newname test

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

        This command displays the security descriptor for the specified Registry item:

        Get-Acl -path hkcu:\environment\testnew | Format-List -property *

    TASK: Managing Registry Entries

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

        This command displays the value name and value data for each Registry entry in the HKEY_CURRENT_USER\Environment Registry key:

        Get-Itemproperty -path hkcu:\Environment

        The Default Registry entry is returned only if it has a value.
        ————————– EXAMPLE 2 ————————–

        This command displays the value name and value data for the Temp Registry entry in the HKEY_CURRENT_USER\Environment Registry key:

        Get-Itemproperty -path hkcu:\Environment -name Temp

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

        This command creates the pstest Registry entry in the HKEY_CURRENT_USER key and sets its value to pstestvalue:

        New-Itemproperty -path hkcu:\environment -name “pstest” -value “pstestvalue”

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

        This command updates the value of the pstest Registry entry to updatedvalue in the HKEY_CURRENT_USER\Environment key:

        Set-Itemproperty -path hkcu:\environment -name pstest
        -value “updatedvalue”

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

        This command renames the value name of the pstest Registry entry to pstestnew in the HKEY_CURRENT_USER\Environment key:

        Rename-Itemproperty -path hkcu:\environment -name pstest `
        -newname pstestnew

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

        This command copies the pstestnew Registry entry from the HKEY_CURRENT_USER\Environment key to the HKEY_CURRENT_USER\Environment\testnewcopy key:

        Copy-Itemproperty -path hkcu:\environment `
        -destination hkcu:\environment\testnewcopy -name pstestnew

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

        The command moves the pstestnew Registry entry from the HKEY_CURRENT_USER\environment\testnewcopy key to the HKEY_CURRENT_USER\environment\testnew key:

        Move-Itemproperty -path hkcu:\environment\testnewcopy ‘
        -destination hkcu:\environment\testnew -name pstestnew

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

        This command clears the value of the pstestnew Registry entry in the HKEY_CURRENT_USER\Environment\testnew key:

        Clear-Itemproperty -path hkcu:\environment\testnew -name pstestnew

        You can use the Clear-Item cmdlet to clear the value of the default Registry entry for a subkey. For example, the following command clears the value of the default entry of the HKEY_CURRENT_USER\Environment\testnew Registry key:

        Clear-Item -path hkcu:\environment\testnew
        ————————– EXAMPLE 9 ————————–

        This command removes the pstestnew Registry entry from the HKEY_CURRENT_USER\Environment\testnew Registry key:

        Remove-Itemproperty -path hkcu:\environment\testnew `
        -name pstestnew

        ————————– EXAMPLE 10 ————————–

        This command updates the value of the default Registry entry in the HKEY_CURRENT_USER\Environment\testnew key to “default value”:

        Set-Itemproperty -path hkcu:\environment\testnew `
        -name “(default)” -value “default value”

        You can also update the default value of a Registry key by using the Set-Item cmdlet. For example, the following command updates the default value of the testnew key:

        Set-Item -path hkcu:\environment\testnew -value “another default value”

DYNAMIC PARAMETERS
    -Type <Microsoft.Win32.RegistryValueKind>
        Specifies the data types to use when storing values in the Registry, or identifies the data type of a value in the Registry.

            String
                Specifies a null-terminated string. Equivalent to REG_SZ.

            ExpandString
                Specifies a null-terminated string that contains unexpanded references to Environment Variables that are expanded when the value is retrieved. Equivalent to REG_EXPAND_SZ.

            Binary
                Specifies binary data in any form. Equivalent to REG_BINARY.

            DWord
                Specifies a 32-bit binary number. Equivalent to REG_DWORD.

            MultiString
                Specifies an array of null-terminated strings terminated by two null characters. Equivalent to REG_MULTI_SZ.

            QWord
                Specifies a 64-bit binary number. Equivalent to REG_QWORD.

            Unknown
                Indicates an unsupported Registry data type, such as REG_RESOURCE_LIST.

        Cmdlets Supported: Set-Item

NOTES

RELATED LINKS
    about_providers

Function

PROVIDER NAME
    Function

DRIVES
    Function:

SYNOPSIS
    Provides access to the Functions defined in Windows PowerShell.

DESCRIPTION
    The Windows PowerShell Function provider lets you get, add, change, clear, and delete the Functions and filters in Windows PowerShell.

    A Function is a named block of code that performs an action. When you type the Function name, the code in the Function runs. A filter is a named block of code that establishes conditions for an action. You can type the name of the filter in place of the condition, such as in a Where-Object command.

    In the Function: drive, Functions are preceded by the label “Function” and filters are preceded by the label “Filter”, but they operate properly when used in the correct context regardless of the label.

    The Function provider is a flat namespace that contains only the Function and filter objects. Neither Functions nor filters have child items.

    Each Function is an instance of the System.Management.Automation.FunctionInfo class. Each filter is an instance of the System.Management.Automation.FilterInfo class.

    The examples in this section show how to manage Functions, but the same methods can be used with filters.

    The Function provider exposes its data store in the Function: drive. To work with Functions, you can change your location to the Function: drive (“Set-Location Function:”). Or, you can work from another Windows PowerShell drive. To reference a Function from another location, use the drive name (Function:) in the path.

    The Function provider supports all of the cmdlets whose names contain the Item noun (the Item cmdlets), except for Invoke-Item. And, it supports the Get-Content and Set-Content cmdlets. However, it does not support the cmdlets whose names contain the ItemProperty noun (the ItemProperty cmdlets), and it does not support the Filter parameter in any cmdlet.

    All changes to the Functions affect the current console only. To save the changes, add the Function to the Windows PowerShell profile, or use Export-Console to save the current console.

CAPABILITIES

TASKS
    TASK: Getting to the Function: Drive

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

        Changes the current location to the Function: drive. You can use this command from any drive in Windows PowerShell. To return to a file system drive, type the drive name. For example, type “Set-Location c:”.

        Set-Location Function:

    TASK: Getting Functions

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

        This command gets the list of all the Functions in the current session. You can use this command from any Windows PowerShell drive.

        Get-ChildItem -path Function:

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

        This command gets the “man” Function from the Function: drive. It uses the Get-Item cmdlet to get the Function. The pipeline operator (|) sends the result to Format-Table.

        The Wrap parameter directs text that does not fit on the line onto the next line. The Autosize parameter resizes the table columns to accommodate the text.

        Get-Item -path man | Format-Table -wrap -autosize

        If you are in a different drive, add the drive name (Function:) to the path.
        ————————– EXAMPLE 3 ————————–

        These commands both get the Function named “c:”. The first command can be used in any drive. The second command is used in the Function: drive.

        Because the name ends in a colon, which is the syntax for a drive, you must qualify the path with the drive name. Within the Function: drive, you can use either format. In the second command, the dot (.) represents the current location.

        c:\PS> Get-Item -path Function:c:

        PS Function> Get-Item -path .\c:

    TASK: Creating a Function

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

        This command uses the New-Item cmdlet to create a Function called “HKLM:”. The expression in braces is the script block that is represented by the Function name.

        New-Item -path Function:hklm: -value {Set-Location hklm:}

        You can also create a Function by typing it at the Windows PowerShell command line. For example, tpe “function:hklm: {Set-Location hklm:}”. If you are in the Function: drive, you can omit the drive name.

        Because you cannot specify the “Filter” label in New-Item, filters are labeled as Functions, but they operate properly with any label. To create a filter with the “Filter” label, type the filter at the command line. For example, type “filter:Running {$_.Status -eq “Running”}”.
        ————————– EXAMPLE 2 ————————–

        This command uses the New-Item cmdlet to create a Function called Csrss. It uses the Options dynamic parameter to specify a value of ReadOnly for the Options property of the Function.

        New-Item -path Function: -name csrss -options readonly -value {Get-Process csrss}

        This command works from any location. If you are in the Function: drive, you can use a dot (.) to specify the path. The dot represents the current location.

    TASK: Deleting a Function

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

        This command deletes the “hklm:” Function from the current session.

        Remove-Item Function:hklm:

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

        This command deletes all the Functions from the current session except for the Functions whose Options property has a value of Constant. Without the Force parameter, the command does not delete Functions whose Options property has a value of ReadOnly.

        Remove-Item Function:* -force

        When you delete all the Functions, the command prompt changes because the prompt Function, which defines the content of the command prompt, is deleted.

    TASK: Displaying the Properties and Methods of Functions

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

        This command uses the Get-Item cmdlet to get all the Functions. The pipeline operator sends the results to the Get-Member cmdlet, which displays the methods and the properties of the object.

        Get-Item -path Function:* | Get-Member

        When you pipe a collection of objects (such as the collection of Functions in the Function: drive) to Get-Member, Get-Member evaluates each object in the collection separately and returns information about each object type that it finds. If all of the objects are of the same type, it returns information about the single object type. In this case, all of the Functions are FunctionInfo objects.

        To get information about the collection of FunctionInfo objects, use the InputObject parameter of Get-Member. For example, type “Get-Member -InputObject (Get-Item Function:*)”. When you use the InputObject parameter, Get-Member evaluates the collection, not the objects in the collection.
        ————————– EXAMPLE 2 ————————–

        This command lists the values of the properties of the “prompt” Function. It uses the Get-Item cmdlet to get an object that represents the “prompt” Function. The pipeline operator (|) sends the results to the Format-List command. The Format-List command uses the Property parameter with a wildcard character (*) to format and to display the values of all of the properties of the “prompt” Function.

        Get-Item Function:prompt | Format-List -property *

    TASK: Changing the Properties of a Function

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

        You can use the Set-Item cmdlet with the Options dynamic parameter to change the value of the Options property of a Function.

        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.

        Set-Item -path Function:prompt -options “AllScope,ReadOnly”

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

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

        Set-Item -path Function:prompt -value {‘PS ‘+ $(Get-Date -format t) + ” ” + $(Get-Location) + ‘> ‘}

        The change affects both the Definition and ScriptBlock properties of the FunctionInfo object. To see the effect of the change, type “Get-Item -path Function:prompt | Format-List -property *”.
        ————————– EXAMPLE 3 ————————–

        This command uses the Rename-Item cmdlet to change the name of the “help” Function to “gh”.

        Rename-Item -path Function:help -newname gh

    TASK: Copying a Function

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

        This command copies the “prompt” Function to “oldPrompt”, effectively creating a new name for the script block that is associated with the prompt Function. You can use this to save the original prompt Function if you plan to change it.

        The Options property of the new Function has a value of None. To change the value of the Options property, use Set-Item.

        Copy-Item -path Function:prompt -destination Function:oldPrompt

DYNAMIC PARAMETERS
    -Options <System.Management.Automation.ScopedItemOptions>
        Determines the value of the Options property of a Function.

            None
                No options. “None” is the default.

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

            Private
                The Function is visible only in the current scope (not in child scopes).

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

            AllScope
                The Function is copied to any new scopes that are created.

        Cmdlets Supported: New-Item, Set-Item

NOTES

RELATED LINKS
    about_functions
    about_providers

FileSystem

PROVIDER NAME
    FileSystem

DRIVES
    C, D

SYNOPSIS
    Provides access to files and directories.

DESCRIPTION
    The Windows PowerShell FileSystem provider lets you get, add, change, clear, and delete files and directories in Windows PowerShell.

    The FileSystem provider exposes Windows PowerShell drives that correspond to the logical drives configured on your computer, including drives mapped to network shares. For example, a computer with one floppy disk drive, one hard disk drive, and one mapped network shared directory might have drives named A, C, and Z. The FileSystem provider exposes Windows PowerShell drives that correspond directly to A, C, and Z, allowing you to reference these drives from within Windows PowerShell. For example, to reference drive C, you use C:, as shown in the following example:

     Get-ChildItem c:

    The command returns all the contents on the C drive, including files and directories. When you reference a specific directory or file through the FileSystem provider, you must provide the information necessary to identify that directory or file. This means that, in some cases, you must provide a fully qualified name. A fully qualified name includes the drive name (along with a colon), any directory and subdirectory names, and the file name (when applicable). For instance, the following example shows the fully qualified name for the Shell.dll file, which is located in the System32 subdirectory of the Windows directory on the C drive:

    c:\windows\system32\shell.dll

    As you can see, each element of the fully qualified name is separated by a backslash (\). Windows PowerShell also allows you to use a forward slash (/) to be consistent with a variety of other shells.

    In some cases, you do not need to supply a fully-qualified name when referencing a file or directory. For example, if you want to access a file in your current working location, you need to provide only the file name. If your current working location is c:\windows, you can view a list of all the .dll files in that directory by using the following command:

     Get-ChildItem *.dll

    If your working directory is something other than c:\windows, such as c:\program files\Windows PowerShell, your command might need to include the fully qualified name:

     Get-ChildItem c:\windows\*.dll

    In some cases, you can use relative references to a location. If your working location is c:\windows, and you want to view a list of .dll files in the c:\windows\system32 directory, you can use the following command:

     Get-ChildItem .\system32\*.dll

    The period before \system32 represents the current working location.

    In some situations, your current working location will be on a drive other than a FileSystem drive. If this is the case, you must always include the name of the target drive in your reference. For example, suppose that your current working location is the env: drive. To view the contents of the C drive, you would use the following command:

     Get-ChildItem c:

CAPABILITIES

TASKS
    TASK: Navigating the File System

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

        This command gets the current location:

        Get-Location

        The Get-Location cmdlet includes the Functionality of commands like the cd command in the Windows Command Prompt and the pwd command in UNIX. For more information, type:

            Get-Help Get-Location
        ————————– EXAMPLE 2 ————————–

        This command sets the current location:

        Set-Location C:

    TASK: Getting File and Directory Information

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

        This command gets all the files and directories in the current directory:

        Get-ChildItem

        By default, the Get-ChildItem cmdlet does not recurse. If files and folders are present in the current directory when you run this command, a System.IO.FileInfo object and a System.IO.DirectoryInfo object are returned.
        ————————– EXAMPLE 2 ————————–

        This command gets all the files and directories in the current directory by using Get-ChildItem:

        Get-ChildItem | Where-Object {!$_.psiscontainer}

        It pipes the results to Where-Object, which examines the PSIsContainer property and lets only the objects that are not (!) containers through the pipeline.
        ————————– EXAMPLE 3 ————————–

        This command gets all the files and directories in the current directory by using Get-ChildItem. It pipes the results to Where-Object, which examines the PSIsContainer property and lets only the objects that are containers through the pipeline.

        Get-ChildItem | Where-Object {$_.psiscontainer}

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

        This command gets all the files and directories in the current directory by using Get-ChildItem:

        Get-Item -path a | Format-List *

        It pipes the results to the Where-Object cmdlet, which examines the PSIsContainer property and lets only the objects that are containers through the pipeline.
        ————————– EXAMPLE 5 ————————–

        This command uses the Get-Item cmdlet to get information about the Test.txt file:

        Get-Item -path test.txt | Format-List *

        The Format-List cmdlet is used to display all the properties of the resulting object.

    TASK: Copying Files and Directories

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

        This command copies the A.txt file from the C:\A directory to the C:\A\Bb directory:

        Copy-Item -path C:\a\a.txt -destination C:\a\bb\a.txt

        It overwrites files in the destination directory without prompting for confirmation.
        ————————– EXAMPLE 2 ————————–

        This command copies all the files in the C:\A\Bb directory that have the .txt file name extension to the C:\A\Cc\Ccc\ directory:

        Copy-Item -path C:\a\bb\*.txt -destination C:\a\cc\ccc\

        It uses the original names of the files. The command overwrites the existing files in the destination directory without prompting for confirmation.
        ————————– EXAMPLE 3 ————————–

        Copies all the directories and files in the C:\a directory to the C:\c directory. If any of the directories to copy already exist in the destination directory, the command will fail unless you specify the Force parameter.

        Copy-Item -path C:\a\* -destination C:\c -recurse

    TASK: Moving Files and Directories

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

        This command moves the C.txt file in the C:\A directory to the C:\A\Aa directory:

        Move-Item -path C:\a\c.txt -destination C:\a\aa

        The command will not automatically overwrite an existing file that has the same name. To force the cmdlet to overwrite an existing file, specify the Force parameter.
        ————————– EXAMPLE 2 ————————–

        This command moves the C:\A directory and all its contents to the C:\B directory:

        Move-Item -path C:\a -destination C:\b

        You cannot move a directory when that directory is the current location.

    TASK: Managing File Content

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

        This command appends the “test content” string to the Test.txt file:

        Add-Content -path test.txt -value “test content”

        The existing content in the Test.txt file is not deleted.
        ————————– EXAMPLE 2 ————————–

        This command gets the contents of the Test.txt file and displays them in the console:

        Get-Content -path test.txt

        You can pipe the contents of the file to another cmdlet. For example, the following command reads the contents of the Test.txt file and then supplies them as input to the ConvertTo-Html cmdlet:

        Get-Content -path test.txt | ConvertTo-Html
        ————————– EXAMPLE 3 ————————–

        This command replaces the contents of the Test.txt file with the “test content” string:

        Set-Content -path test.txt -value “test content”

        It overwrites the contents of Test.txt. You can use the Value parameter of the New-Item cmdlet to add content to a file when you create it.

    TASK: Managing Security Descriptors

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

        This command returns a System.Security.AccessControl.FileSecurity object:

        Get-Acl -path test.txt | Format-List -property *

        For more information about this object, pipe the command to the Get-Member cmdlet. Or, see “FileSecurity Class” in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=145718.
        ————————– EXAMPLE 2 ————————–

        This command returns a System.Security.AccessControl.DirectorySecurity object:

        Get-Acl -path test_directory | Format-List -property *

        For more information about this object, pipe the command to the Get-Member cmdlet. Or, see “DirectorySecurity Class” in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=145736.

    TASK: Creating Files and Directories

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

        This command creates the Logfiles directory on the C drive:

        New-Item -path c:\ -name logfiles -type directory

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

        This command creates the Log2.txt file in the C:\Logfiles directory and then adds the “test log” string to the file:

        New-Item -path c:\logfiles -name log.txt -type file

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

        Creates a file called Log2.txt in the C:\logfiles directory and adds the string “test log” to the file.

        New-Item -path c:\logfiles -name log2.txt -type file -value “test log”

    TASK: Renaming Files and Directories

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

        This command renames the A.txt file in the C:\A directory to B.txt:

        Rename-Item -path c:\a\a.txt -newname b.txt

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

        This command renames the C:\A\Cc directory to C:\A\Dd:

        Rename-Item -path c:\a\cc -newname dd

    TASK: Deleting Files and Directories

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

        This command deletes the Test.txt file in the current directory:

        Remove-Item -path test.txt

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

        This command deletes all the files in the current directory that have the .xml file name extension:

        Remove-Item -path *.xml

    TASK: Starting a Program by Invoking an Associated File

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

        The first command uses the Get-Service cmdlet to get information about local services.

        It pipes the information to the Export-Csv cmdlet and then stores that information in the Services.csv file.

        The second command uses Invoke-Item to open the Services.csv file in the program associated with the .csv extension:

        Get-Service | Export-Csv -path services.csv

        Invoke-Item -path services.csv

DYNAMIC PARAMETERS
    -Encoding <Microsoft.PowerShell.Commands.FileSystemCmdletProviderEncoding>

            Unknown
                The encoding type is unknown or invalid. The data can be treated as binary.

            String
                Uses the encoding type for a string.

            Unicode
                Encodes in UTF-16 format using the little-endian byte order.

            Byte
                Encodes a set of characters into a sequence of bytes.

            BigEndianUnicode
                Encodes in UTF-16 format using the big-endian byte order.

            UTF8
                Encodes in UTF-8 format.

            UTF7
                Encodes in UTF-7 format.

            ASCII
                Uses the encoding for the ASCII (7-bit) character set.

        Cmdlets Supported: Add-Content, Get-Content, Set-Content

    -Delimiter <System.String>
        Specifies the delimiter to use when reading the file. The default is “\n” (end of line).

        Cmdlets Supported: Get-Content

    -Wait <System.Management.Automation.SwitchParameter>
        Waits for content to be appended to the file. If content is appended, it returns the appended content. If the content has changed, it returns the entire file.

        When waiting, Get-Content checks the file once each second until you interrupt it, such as by pressing CTRL+C.

        Cmdlets Supported: Get-Content

NOTES

RELATED LINKS
    about_providers

Environment

PROVIDER NAME
    Environment

DRIVES
    Env:

SYNOPSIS
    Provides access to the Windows Environment Variables.

DESCRIPTION
    The Windows PowerShell Environment provider lets you get, add, change, clear, and delete Windows Environment Variables in Windows PowerShell.

    The Environment provider is a flat namespace that contains only objects that represent the Environment Variables. The Variables have no child items.

    Each Environment Variable is an instance of the System.Collections.DictionaryEntry class. The name of the Variable is the dictionary key. The value of the Environment Variable is the dictionary value.

    The Environment provider exposes its data store in the Env: drive. To work with Environment Variables, change your location to the Env: drive (“Set-Location env:”), or work from another Windows PowerShell drive. To reference an Environment Variable from another location, use the Env: drive name in the path.

    The Environment Variable provider supports all the cmdlets that contain the Item noun except for Invoke-Item. And, it supports the Get-Content and Set-Content cmdlets. However, it does not support the cmdlets that contain the ItemProperty noun, and it does not support the Filter parameter in any cmdlet.

    Environment Variables must conform to the usual naming standards. Additionally, the name cannot include the equal sign (=).

    Changes to the Environment Variables affect the current session only. To save the changes, add the changes to the Windows PowerShell profile, or use Export-Console to save the current session.

CAPABILITIES

TASKS
    TASK: Getting to the Env: Drive

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

        This command changes the current location to the Env: drive:

        Set-Location env:

        You can use this command from any drive in Windows PowerShell. To return to a file system drive, type the drive name. For example, type:

            Set-Location c:

    TASK: Getting Environment Variables

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

        This command lists all the Environment Variables in the current session:

        Get-ChildItem -path env:

        You can use this command from any Windows PowerShell drive.
        ————————– EXAMPLE 2 ————————–

        This command gets the WINDIR Environment Variable:

        Get-ChildItem -path env:windir

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

        This command gets a list of all the Environment Variables in the current session and then sorts them by name:

        Get-ChildItem | Sort-Object -property name

        By default, the Environment Variables appear in the order that Windows PowerShell discovers them. This command is submitted in the Env: drive.

        When you run this command from another drive, add the Path parameter with a value of Env:.

    TASK: Creating a New Environment Variable

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

        This command creates the USERMODE Environment Variable with a value of Non-Admin:

        New-Item -path . -name USERMODE -value Non-Admin

        Because the current location is in the Env: drive, the value of the Path parameter is a dot (.). The dot represents the current location.

        If you are not in the Env: drive, the value of the Path parameter would be Env:.

    TASK: Displaying the Properties and Methods of Environment Variables

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

        This command uses the Get-ChildItem cmdlet to get all the Environment Variables:

        Get-ChildItem -path env: | Get-Member

        The pipeline operator (|) sends the results to Get-Member, which displays the methods and properties of the object.

        When you pipe a collection of objects to Get-Member, such as the collection of Environment Variables in the Env: drive, Get-Member evaluates each object in the collection separately. Get-Member then returns information about each object type that it finds. If all the objects are of the same type, it returns information about the single object type. In this case, all the Environment Variables are DictionaryEntry objects.

        To get information about the collection of DictionaryEntry objects, use the InputObject parameter of Get-Member. For example, type:

            Get-Member -inputobject (Get-ChildItem env:)

        When you use the InputObject parameter, Get-Member evaluates the collection, not the objects in the collection.
        ————————– EXAMPLE 2 ————————–

        This command lists the values of the properties of the WINDIR Environment Variable:

        Get-Item env:windir | Format-List -property *

        It uses the Get-Item cmdlet to get an object that represents the WINDIR Environment Variable. The pipeline operator (|) sends the results to the Format-List command. It uses the Property parameter with a wildcard character (*) to format and display the values of all the properties of the WINDIR Environment Variable.

    TASK: Changing the Properties of an Environment Variable

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

        This command uses the Rename-Item cmdlet to change the name of the USERMODE Environment Variable that you created to USERROLE:

        Rename-Item -path env:USERMODE -newname USERROLE

        This change affects the Name, Key, and PSPath properties of the DictionaryEntry object.

        Do not change the name of an Environment Variable that the system uses. Although these changes affect only the current session, they might cause the system or a program to operate incorrectly.
        ————————– EXAMPLE 2 ————————–

        This command uses the Set-Item cmdlet to change the value of the USERROLE Environment Variable to Administrator:

        Set-Item -path env:USERROLE -value Administrator

    TASK: Copying an Environment Variable

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

        This command copies the value of the USERROLE Environment Variable to the USERROLE2 Environment Variable:

        Copy-Item -path env:USERROLE -destination env:USERROLE2

    TASK: Deleting an Environment Variable

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

        This command deletes the USERROLE2 Environment Variable from the current session:

        Remove-Item -path env:USERROLE2

        You can use this command in any Windows PowerShell drive. If you are in the Env: drive, you can omit the drive name from the path.
        ————————– EXAMPLE 2 ————————–

        This command deletes the USERROLE Environment Variable.

        Clear-Item -path env:USERROLE

DYNAMIC PARAMETERS

NOTES
    The Environment provider does not support any dynamic parameters.

RELATED LINKS
    about_providers

Alias

PROVIDER NAME
    Alias

DRIVES
    Alias:

SYNOPSIS
    Provides access to the Windows PowerShell Aliases and the values that they represent.

DESCRIPTION
    The Windows PowerShell Alias provider lets you get, add, change, clear, and delete Aliases in Windows PowerShell.

    An Alias is an alternate name for a cmdlet, Function, or executable file. Windows PowerShell includes a set of built-in Aliases. And, you can add your own Aliases to the current session and to your Windows PowerShell profile.

    The Alias provider is a flat namespace that contains only the Alias objects. The Aliases have no child items.

    Each Alias is an instance of the System.Management.Automation.AliasInfo class.

    The Alias provider exposes its data store in the Alias: drive. To work with Aliases, you can change your location to the Alias: drive by using the following command:

        Set-Location Alias:

    Or, you can work from any other Windows PowerShell drive. To reference an Alias from another location, use the Alias: drive name in the path.

    Windows PowerShell includes a set of cmdlets that are designed to view and to change Aliases:

        Export-Alias
        Get-Alias
        Import-Alias
        New-Alias
        Set-Alias

    When you use these cmdlets, you do not need to specify the Alias: drive in the name.

    The Alias provider supports all the cmdlets that have the Item noun except for the Invoke-Item cmdlet. And, it supports the Get-Content and Set-Content cmdlets. The Alias provider does not support the cmdlets that have the ItemProperty noun. And, the Alias provider does not support the Filter parameter in any cmdlet.

    All changes to the Aliases affect the current session only. To save the changes, add the changes to the Windows PowerShell profile. Or, use the Export-Alias and Import-Alias cmdlets.

CAPABILITIES

TASKS
    TASK: Getting to the Alias: Drive

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

        This command changes the current location to the Alias: drive. You can use this command from any drive in Windows PowerShell. To return to a file system drive, type the drive name. For example, type “Set-Location c:”.

        Set-Location Alias:

    TASK: Getting Aliases

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

        This command gets a list of all the Aliases in the current session. You can use this command in any Windows PowerShell drive.

        Get-Item -path Alias:

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

        This command gets the “ls” Alias. Because it includes the path, you can use it in any Windows PowerShell drive.

        Get-Item -path Alias:ls

        If you are in the Alias: drive, you can omit the drive name from the path.
        ————————– EXAMPLE 3 ————————–

        This command gets a list of the Aliases that are associated with the Get-ChildItem cmdlet. It uses the Definition property, which stores the cmdlet name.

        Get-Item -path Alias:* | Where-Object {$_.Definition -eq “Get-ChildItem“}

        When the Aliased item is an executable file, the Definition contains the fully qualified path of the file.
        ————————– EXAMPLE 4 ————————–

        This command gets the list of all the Aliases when the current location is the Alias: drive. It uses a wildcard character (*) to indicate all the contents of the current location.

        Get-Item -path *

        In the Alias: drive, a dot (.), which represents the current location, and a wildcard character (*), which represents all items in the current location, have the same effect. For example, “Get-Item -path .” or “Get-Item *” produce the same result.

    TASK: Creating a New Alias

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

        This command creates the “serv” Alias for the Get-Service cmdlet. Because the current location is in the Alias: drive, the value of the Path parameter is a dot (.). The dot represents the current location.

        This command also uses the Options dynamic parameter to set the AllScope and Constant options on the Alias. The Options parameter is available in the New-Item cmdlet only when you are in the Alias: drive.

        New-Item -path . -name serv -value Get-Service -Options “AllScope,Constant”

        If you are in the Alias: drive, you can omit the drive name from the path.
        ————————– EXAMPLE 2 ————————–

        You can create an Alias for any item that invokes a command. This command creates the “np” Alias for Notepad.exe.

        New-Item -path Alias:np -value c:\windows\notepad.exe

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

        You can create an Alias for any Function. You can use this feature to create an Alias that includes both a cmdlet and its parameters.

        The first command creates the CD32 Function, which changes the current directory to the System32 directory. The second command creates the “go” Alias for the CD32 Function. The semi-colon (;) is the command separator.

        When the command is complete, you can use either “CD32” or “go” to invoke the Function.

        Function CD32 {Set-Location -path c:\windows\system32} Set-Item -path Alias:go -value CD32

    TASK: Displaying the Properties and Methods of Aliases

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

        This command uses the Get-Item cmdlet to get all Aliases. The pipeline operator (|) sends the results to the Get-Member cmdlet, which displays the methods and properties of the object.

        Get-Item -path Alias:* | Get-Member

        When you pipe a collection of objects to Get-Member, such as the collection of Aliases in the Alias: drive, Get-Member evaluates each object in the collection separately. Then, Get-Member returns information about each object type that it finds. If all the objects are of the same type, it returns information about the single object type. In this case, all the Aliases are AliasInfo objects.

        To get information about the collection of AliasInfo objects, use the InputObject parameter of Get-Member. For example, use the following command:

            Get-Member -InputObject (Get-Item Alias:*)

        When you use InputObject, Get-Member evaluates the collection, not the objects in the collection.
        ————————– EXAMPLE 2 ————————–

        This command lists the values of the properties of the “dir” Alias. It uses the Get-Item cmdlet to get an object that represents the “dir” Alias. The pipeline operator (|) sends the results to the Format-List command. The Format-List command uses the Property parameter with a wildcard character (*) to format and display the values of all the “dir” Alias properties.

        Get-Item Alias:dir | Format-List -property *

    TASK: Changing the Properties of an Alias

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

        You can use the Set-Item cmdlet with the Options dynamic parameter to change the value of the Options property of an Alias.

        This command sets the AllScope and ReadOnly options for the “dir” Alias. The 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.

        Set-Item -path Alias:dir -options “AllScope,ReadOnly”

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

        This command uses the Set-Item cmdlet to change the “gp” Alias so that it represents the Get-Process cmdlet instead of the Get-ItemProperty cmdlet. The Force parameter is required because the value of the Options property of the “gp” Alias is set to ReadOnly. Because the command is submitted from within the Alias: drive, the drive is not specified in the path.

        Set-Item -path gp -value Get-Process -force

        The change affects the four properties that define the association between the Alias and the command. To view the effect of the change, type the following command:

            Get-Item -path gp | Format-List -property *
        ————————– EXAMPLE 3 ————————–

        This command uses the Rename-Item cmdlet to change the “popd” Alias to “pop”.

        Rename-Item -path Alias:popd -newname pop

    TASK: Copying an Alias

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

        This command copies the pushd Alias so that a new push Alias is created for the Push-Location cmdlet.

        Copy-Item -path Alias:pushd -destination Alias:push

        When the new Alias is created, its Description property has a null value. And, its Option property has a value of None.

        If the command is issued from within the Alias: drive, you can omit the drive name from the value of the Path parameter.

    TASK: Deleting an Alias

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

        This command deletes the serv Alias from the current session. You can use this command in any Windows PowerShell drive.

        Remove-Item -path Alias:serv

        If you are in the Alias: drive, you can omit the drive name from the path.
        ————————– EXAMPLE 2 ————————–

        This command deletes Aliases that begin with “s”. It does not delete read-only Aliases.

        Clear-Item -path Alias:s*

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

        This command deletes all Aliases from the current session, except those with a value of Constant for their Options property. Without the Force parameter, the command does not delete Aliases whose Options property has a value of ReadOnly.

        Remove-Item Alias:* -force

DYNAMIC PARAMETERS
    -Options <System.Management.Automation.ScopedItemOptions>
        Determines the value of the Options property of an Alias.

            None
                No options. This value is the default.

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

            Private
                The Alias is visible only in the current scope, not in the child scopes.

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

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

        Cmdlets Supported: New-Item, Set-Item

NOTES

RELATED LINKS
    about_aliases
    about_providers

WSMan

PROVIDER NAME
    WSMan

DRIVES
    WSMan

SYNOPSIS
    Provides access to Web Services for Management (WS-Management) configuration information.

DESCRIPTION
    The WS-Management provider for Windows PowerShell lets you add, change, clear, and delete WS-Management configuration data on local or remote computers.

    The WS-Management provider exposes a Windows PowerShell drive with a directory structure that corresponds to a logical grouping of WS-Management configuration settings. These groupings are known as containers.

    — Client
    You can configure various aspects of the WS-Management client. The configuration information is stored in the Registry.

    — Service
    You can configure various aspects of the WS-Management service. The configuration information is stored in the Registry.
    Note: Service configuration is sometimes referred to as Server configuration.

    — Shell
    You can configure various aspects of the WS-Management shell, such as the setting to allow remote shell access (AllowRemoteShellAccess) and the maximum number of concurrent users allowed (MaxConcurrentUsers).

    — Listener
    You can create and configure a listener. A listener is a management service that implements the WS-Management protocol to send and to receive messages.

    — Plugin
    Plug-ins are loaded and used by the WS-Management service to provide various Functions. By default, Windows PowerShell provides three plug-ins: the Event Forwarding plug-in, the Microsoft.PowerShell plug-in, and the Windows Management Instrumentation (WMI) Provider plug-in. These three plug-ins support event forwarding, configuration, and WMI access.

    — ClientCertificate
    You can create and configure a client Certificate. A client Certificate is used when the WS-Management client is configured to use Certificate authentication.

    Directory Hierarchy of the WS-Management Provider
    —————
    The directory hierarchy of the WS-Management provider for the local computer is as follows:

    WSMan:\localhost
    — Client
    — Service
    — Shell
    — Listener
    —— <Specific_Listener>
    — Plugin
    —— Event Forwarding Plugin
    ——— InitializationParameters
    ——— Resources
    ———— Security
    —— Microsoft.Powershell
    ——— InitializationParameters
    ——— Resources
    ———— Security
    —— WMI Provider
    ——— InitializationParameters
    ——— Resources
    ———— Security
    — ClientCertificate

    The directory hierarchy of the WS-Management provider for a remote computer is the same as a local computer. However, in order to access the configuration settings of a remote computer, you need to make a connection to the remote computer using Connect-WSMan. Once a connection is made to a remote computer, the name of the remote computer shows up in the provider.

    WSMan:\<Remote_Computer_Name>
    — Client
    — Service
    — Shell
    — Listener
    —— <Specific_Listener>
    — Plugin
    —— Event Forwarding Plugin
    ——— InitializationParameters
    ——— Resources
    ———— Security
    —— Microsoft.Powershell
    ——— InitializationParameters
    ——— Resources
    ———— Security
    —— WMI Provider
    ——— InitializationParameters
    ——— Resources
    ———— Security
    — ClientCertificate

    Custom Provider Help
    ——————–
    The Listener, Plugin (IntitializationParameters, Resources, Security) and ClientCertificate provider paths provide specific New-Item support. Type “Get-Help New-Item” in the relevant path for custom help.

CAPABILITIES

TASKS
    TASK: Navigating the WSMan: Drive

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

        This command uses the Set-Location cmdlet to change the current location to the WSMan: drive.

        Set-Location WSMan:

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

        This command uses the Set-Location command to change the current location to the root location in the Localhost store location. Use a backslash (\) or forward slash (/) to indicate a level of the WSMan: drive.

        Set-Location -Path Localhost

        If you are not in the WSMan: drive, begin the path with the drive name.
        ————————– EXAMPLE 3 ————————–

        This command uses the Set-Location command to change the current location to the root location in the remote system store location. Use a backslash (\) or forward slash (/) to indicate a level of the WSMan: drive.

        Set-Location -Path WSMan:\SERVER01

        If you are not in the WSMan: drive, begin the path with the drive name.

        The above command assume that a connection to the remote system already exists. If a connection has not been made to the remote system, then a connection could be make immediately prior to navigating to the root location in the remote system store location. For example:

         WSMan-Connect SERVER01
         Set-Location -Path WSMan:\SERVER01
        ————————– EXAMPLE 4 ————————–

        This command uses the Set-Location command to change the current location to the Client location in the Localhost store location. Use a backslash (\) or forward slash (/) to indicate a level of the WSMan: drive.

        Set-Location -Path Localhost\Client

        If you are not in the WSMan: drive, begin the path with the drive name.

    TASK: Displaying the Contents of the WSMan: Drive

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

        This command uses the Get-ChildItem cmdlet to display the WS-Management stores in the Localhost store location.

        Get-ChildItem -path WSMan:\Localhost

        If you are in the WSMan: drive, you can omit the drive name.
        ————————– EXAMPLE 2 ————————–

        This command uses the Get-ChildItem cmdlet to display the WS-Management stores in the remote computer (SERVER01) store location.

        Get-ChildItem -path WSMan:\SERVER01

        If you are in the WSMan: drive, you can omit the drive name.

        The above command assume that a connection to the remote system already exists. If a connection has not been made to the remote system, then a connection could be make immediately displaying the properties and containers in the remote system store location. For example:

         WSMan-Connect SERVER01
         Get-ChildItem -path WSMan:\SERVER01
        ————————– EXAMPLE 3 ————————–

        This command uses the Get-ChildItem cmdlet to display the current WS-Management connections.

        Get-ChildItem -path WSMan:\

        If you are in the WSMan: drive, you can omit the drive name.
        ————————– EXAMPLE 4 ————————–

        This command uses the Get-Item cmdlet to get the properties and containers in the current store.

        Get-ChildItem

        The above command returns a list of properties and containers. For example:
        PS WSMan:\localhost> Get-ChildItem

         WSManConfig: Microsoft.WSMan.Management\WSMan::localhost
        Name                 Value         Type
        —-                             —–         —-
        MaxEnvelopeSizekb     150            System.String
        MaxTimeoutms         60000         System.String
        MaxBatchItems         32000         System.String
        MaxProviderRequests    4294967295     System.String
        Client                                Container
        Service                             Container
        Shell                                 Container
        Listener                             Container
        Plugin                                Container
        ClientCertificate                     Container

DYNAMIC PARAMETERS
    -Address <String>
        Specifies the address for which this listener was created. The value can be one of the following:

        — The literal string “*”. (The wildcard character (*) makes the command bind all the IP addresses on all the network interface cards [NIC].)

        — The literal string “IP:” followed by a valid IP address in either IPv4 dotted-decimal format or in IPv6 cloned-hexadecimal format.

        — The literal string “MAC:” followed by the MAC address of a NIC. For example: MAC:32-a3-58-90-be-cc.

        Note: The Address value is set when creating a Listener.

        Cmdlets Supported: Get-Item

    -AllowRemoteShellAccess <Boolean>
        Enables access to remote shells. If you set this parameter to False, new remote shell connections will be rejected by the server. The default is True.

        Cmdlets Supported: Get-Item, Set-Item

    -AllowUnEncrypted <Boolean>
        Allows the client computer to request unencrypted traffic. By default, the client computer requires encrypted network traffic.

        Cmdlets Supported: Get-Item, Set-Item

    -Arguments <String>
        Specifies the argument string and the command-line arguments that you want to pass to the custom shell. This parameter is optional.

        Cmdlets Supported: Get-Item, Set-Item

    -Basic <Boolean>
        Allows the client computer to use Basic authentication. Basic authentication is a scheme in which the user name and password are sent in clear text to the server or proxy. This method is the least secure method of authentication.

        Cmdlets Supported: Get-Item, Set-Item

    -Capability <Enumeration>
        Specifies an operation that is supported on this Uniform Resource Identifier (URI). You have to create one entry for each type of operation that the URI supports. The following are valid values:

        — Create: Create operations are supported on the URI. The SupportFragment attribute is used if the Create operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported.

        — Delete: Delete operations are supported on the URI. The SupportFragment attribute is used if the Delete operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported.

        — Enumerate: Enumerate operations are supported on the URI. The SupportFragment attribute is not supported for Enumerate operations and should be set to False. The SupportFiltering attribute is valid, and if the plug-in supports filtering, this attribute should be set to True. This operation is not valid for a URI if Shell operations are also supported.

        — Get: Get operations are supported on the URI. The SupportFragment attribute is used if the Get operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported.

        — Invoke: Invoke operations are supported on the URI. The SupportFragment attribute is not supported for Invoke operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported.

        — Put: Put operations are supported on the URI. The SupportFragment attribute is used if the Put operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported.

        — Subscribe: Subscribe operations are supported on the URI. The SupportFragment attribute is not supported for Subscribe operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if Shell operations are also supported.

        — Shell: Shell operations are supported on the URI. The SupportFragment attribute is not supported for Shell operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This operation is not valid for a URI if any other operation is also supported. If a Shell operation is configured for a URI, Get, Put, Create, Delete, Invoke, and Enumerate operations are processed internally within the WS-Management (WinRM) service to manage shells. As a result, the plug-in cannot handle the operations.

        Cmdlets Supported: Get-Item, New-Item, Remove-Item, Set-Item

    -CbtHardeningLevel <String>
        Sets the policy for channel-binding token requirements in authentication requests. The following are valid values:

        — Strict: Any request will be denied unless a channel-binding token is present. This setting guarantees that all connections are secured by the use of channel-binding tokens.

        — Relaxed: If a channel-binding token is present in a request, the connection will be secured. If a channel-binding token is not present, the connection will still be accepted. However, it will be vulnerable to attacks that are prevented by the use of channel-binding tokens.

        — None: Any channel-binding tokens that are supplied are ignored.

        The value of this parameter is only effective for HTTPS connections.

        Cmdlets Supported: Get-Item, Set-Item

    -CertificateThumbprint <String>
        Specifies the thumbprint of the service Certificate.
        This value represents the string of two-digit hexadecimal values in the Thumbprint field of the Certificate. It specifies the digital public key Certificate (X509) of a user account that has permission to perform this action. Certificates are used in client Certificate-based authentication. They can be mapped only to local user accounts, and they do not work with domain accounts. To get a Certificate thumbprint, use the Get-Item or Get-ChildItem cmdlets in the Windows PowerShell Cert: drive.

        Cmdlets Supported: Clear-Item, Get-Item, Set-Item

    -Certificate <Boolean>
        Allows the client to be used for Certificate authentication. The WS-Management client will try to find the Certificate in the computer store. If the client cannot find the Certificate in the computer store, the client tries to find it in the current user store. If no matching Certificate is found, the user receives an error message.

        Cmdlets Supported: Get-Item, Set-Item

    -CredSSP <Boolean>
        Allows the client to use Credential Security Service Provider (CredSSP) authentication.

        CredSSP authentication allows the user to delegate credentials. This option is designed for commands that run on one remote computer but collect data from or run additional commands on other remote computers.

        Caution: CredSSP authentication delegates the user’s credentials from the local computer to a remote computer. This practice increases the security risk of the remote operation. If the remote computer is compromised, when credentials are passed to it, the credentials can be used to control the network session.

        Cmdlets Supported: Get-Item, Set-Item

    -HTTP <Unsigned Short Integer>
        Specifies the port that the client will use when HTTP is used. By default, HTTP uses port 80. You can specify any value from 1 through 65535.

        Cmdlets Supported: Get-Item, Set-Item

    -HTTPS <Unsigned Short Integer>
        Specifies the port that the client will use when HTTPS is used. By default, HTTPS uses port 443. You can specify any value from 1 through 65535.

        Cmdlets Supported: Get-Item, Set-Item

    -Digest <Boolean>
        Allows the client to use Digest authentication. Digest authentication is a challenge-response scheme that uses a server-specified data string for the challenge. Only the client computer can initiate a Digest authentication request. The client computer sends a request to the server to authenticate and receives a token string from the server. Then, the client computer sends the resource request, including the user name and a cryptographic hash of the password combined with the token string. Digest authentication is supported for HTTP and for HTTPS. WinRM Shell client scripts and applications can specify Digest authentication, but the WS-Management service does not accept Digest authentication.

        Note: Digest authentication over HTTP is not considered secure.

        Cmdlets Supported: Get-Item, Set-Item

    -Enabled <Boolean>
        Specifies whether the listener is enabled or disabled. The default is True.

        Cmdlets Supported: Get-Item, Set-Item

    -ExactMatch <Boolean>
        Specifies how to use the security settings that are specified in the Sddl parameter. If the ExactMatch parameter is set to True, the security settings in Sddl are used only to authorize access attempts to the URI exactly as specified by the URI. If ExactMatch is set to false, the security settings in Sddl are used to authorize access attempts to the URIs that begin with the string specified in the URI.

        Cmdlets Supported: Get-Item, Set-Item

    -FileName <String>
        Specifies an input file to use to update the management resource specified by the ResourceURI and SelectorSet.

        Cmdlets Supported: Get-Item, Set-Item

    -FileName (Plugin) <String>
        Specifies the file name of the operations plug-in. Any Environment Variables that are put in this entry will be expanded in the users’ context when a request is received. Because each user could have a different version of the same Environment Variable, each user could have a different plug-in. This entry cannot be blank and must point to a valid plug-in.

        Cmdlets Supported: Get-Item, Set-Item

    -HostName <String>
        Specifies the host name of the computer on which the WS-Management (WinRM) service is running.
        The value must be a fully qualified domain name, an IPv4 or IPv6 literal string, or a wildcard character.

        Cmdlets Supported: Clear-Item, Get-Item, Set-Item

    -IdleTimeOut <Unsigned Long Integer>
        Specifies the maximum time, in milliseconds, that the remote shell will remain open when there is no user activity in the remote shell. The remote shell is automatically deleted after the time that is specified. You can specify any values from 0 through 2147483647. A value of 0 indicates an infinite time-out. The default is 900000 (15 minutes).

        Cmdlets Supported: Get-Item, Set-Item

    -IPv4Filter <String>
        Specifies the IPv4 addresses that listeners can use. The following are valid values:

        — If you leave the parameter blank, no IPv4 addresses can be used.

        — If you enter a wildcard character (*), any IPv4 address can be used.

        — If you enter a list of IP ranges, any IP address in the specified ranges can be used. Separate the ranges by using a comma (,), and specify each range as a pair of IPv4 addresses in dotted-decimal format, separated by a hyphen (-). Make sure that the smaller value occurs first in the pair. The ranges are inclusive.

        Note: An IPv4 literal string consists of four dotted decimal numbers, each in the range 0 though 255. For example: 192.168.0.0.

        Cmdlets Supported: Clear-Item, Get-Item, Set-Item

    -IPv6Filter <String>
        Specifies the IPv6 addresses that listeners can use. The following are valid values:

        — If you leave the parameter blank, no IPv6 addresses can be used.

        — If you enter a wildcard character (*), any IPv6 address can be used.

        — If you enter a list of IP ranges, any IP address in the specified ranges can be used. Separate the ranges by using a comma (,”), and specify each range as a pair of IPv6 addresses in cloned-hexadecimal format, separated by a hyphen (-). Make sure that the smaller value occurs first in the pair. The ranges are inclusive.

        Note: An IPv6 literal string is enclosed in brackets and contains hexadecimal numbers that are separated by colons. For example: [::1] or [3ffe:ffff::6ECB:0101].

        Cmdlets Supported: Clear-Item, Get-Item, Set-Item

    -Issuer <String>
        Specifies the name of the certification authority that issued the Certificate.

        Cmdlets Supported: Get-Item, Set-Item

    -Kerberos <Boolean>
        Allows the client to use Kerberos authentication. Kerberos authentication is a scheme in which the client and server mutually authenticate by using Kerberos Certificates.

        Cmdlets Supported: Get-Item, Set-Item

    -ListeningOn <String>
        Specifies the IP address or all the IP addresses on which the service is actually listening. This is derived from the Address element based upon the actual IPs associated with the listener. The value of the IP address must be in IPv4 dotted-decimal notation or in IPv6 colon-delimited hexadecimal notation. Multiple ListeningOn entries exist, each entry starting with ListeningOn_. For example:
         ListeningOn_1201550598
         ListeningOn_1973755898
         ListeningOn_1508953035
         ListeningOn_1560839940

        Cmdlets Supported: Get-Item

    -MaxBatchItems <Unsigned Long Integer>
        Specifies the maximum number of elements that can be used in a Pull response. You can specify any value from 1 through 4294967295.

        Cmdlets Supported: Get-Item, Set-Item

    -MaxConcurrentUsers <Unsigned Long Integer>
        Specifies the maximum number of users who can concurrently perform remote operations on the same computer through a remote shell. New shell connections will be rejected if they exceed the specified limit. You can specify any value from 1 through 100.

        Cmdlets Supported: Get-Item, Set-Item

    -MaxEnvelopeSizekb <Unsigned Long Integer>
        Specifies the maximum SOAP data in kilobytes. You can specify any value from 32 through 4294967295.

        Cmdlets Supported: Get-Item, Set-Item

    -MaxMemoryPerShellMB <Unsigned Long Integer>
        Specifies the maximum total amount of memory that can be allocated by an active remote shell and all its child processes. You can specify any value from 0 through 2147483647. A value of 0 means that the ability of the remote operations to allocate memory is limited only by the available virtual memory. The default value is 0.

        Cmdlets Supported: Get-Item, Set-Item

    -MaxProcessesPerShell <Unsigned Long Integer>
        Specifies the maximum number of processes that any shell operation is allowed to start. You can specify any number from 0 through 2147483647. A value of 0 allows for an unlimited number of processes. By default, the limit is five processes per shell.

        Cmdlets Supported: Get-Item, Set-Item

    -MaxProviderRequests <Unsigned Long Integer>
        Specifies the maximum number of concurrent requests that are allowed by the service. You can specify any value from 1 through 4294967295. The limit is applied per provider.

        Note: This value is deprecated and should not be used.

        Cmdlets Supported: Get-Item

    -MaxShellsPerUser <Unsigned Long Integer>
        Specifies the maximum number of concurrent shells that any user can remotely open on the same system. If this policy setting is enabled, the user will not be able to open new remote shells if the count exceeds the specified limit. If this policy setting is disabled or is not configured, by default, the limit will be set to two remote shells per user. You can specify any number from 0 through 2147483647. A value of 0 allows for an unlimited number of shells.

        Cmdlets Supported: Get-Item, Set-Item

    -MaxTimeoutMs <Unsigned Long Integer>
        Specifies the maximum time-out in milliseconds that can be used for any request except for Pull requests. You can specify any number from 500 to 4294967295.

        Cmdlets Supported: Get-Item, Set-Item

    -Name <String>
        Specifies a display name for the WS-Management session . You can use the name to refer to the session when using other cmdlets, such as Get-PSSession and Enter-PSSession. The name does not have to be unique to the computer or to the current session.

        Cmdlets Supported: Get-Item, Set-Item

    -Name (Plugin) <String>
        Specifies the display name to use for the plug-in. If an error is returned by the plug-in, the display name will be put in the error XML that is returned to the client application. The name is not locale specific.

        Cmdlets Supported: Get-Item, Set-Item

    -Negotiate <Boolean>
        Allows the client to use Negotiate authentication. Negotiate authentication is a scheme in which the client sends a request to the server to authenticate. The server determines whether to use the Kerberos protocol or NTLM. The Kerberos protocol is selected to authenticate a domain account, and NTLM is selected for local computer accounts. The user name must be specified in the domain\user_name form for a domain user. The user name must be specified in the server_name\user_name format for a local user on a server computer.

        Cmdlets Supported: Get-Item, Set-Item

    -NetworkDelayMs <Unsigned Long Integer>
        Specifies the extra time in milliseconds that the client computer waits to accommodate for network delay time. You can specify any value from 500 through 4294967295.

        Cmdlets Supported: Get-Item, Set-Item

    -Password <String>
        Specifies the password for a local or a domain account. It cannot be NULL.

        The client computer can specify the credentials to use when creating a shell on a computer. The user name must be specified in the domain\user_name form for a domain user. The user name must be specified in the server_name\user_name format for a local user on a server computer.

        If you use this structure, then it should have both the user name and password fields specified. It can be used with Basic, Digest, Negotiate, or Kerberos authentication. The client must explicitly specify the credentials when either Basic or Digest authentication is used.

        Cmdlets Supported: Get-Item, Set-Item

    -Plugin <>
        WS-Management plug-ins are native dynamic link libraries (DLLs) that plug in to and extend the Functionality of WS-Management . The WSW-Management Plug-in API provides Functionality that enables a user to write plug-ins by implementing certain APIs for supported resource URIs and operations. After the plug-ins are configured for either the WS-Management (WinRM) service or for Internet Information Services (IIS), the plug-ins are loaded in the WS-Management host or in the IIS host, respectively. Remote requests are routed to these plug-in entry points to perform operations.

        Cmdlets Supported: New-Item, Remove-Item

    -Port <Unsigned Short Integer>
        Specifies the TCP port for which this listener is created. You can specify any value from 1 through 65535.

        Cmdlets Supported: Get-Item, Set-Item

    -Resource <String>
        Specifies an endpoint that represents a distinct type of management operation or value. A service exposes one or more resources, and some resources can have more than one instance. A management resource is similar to a WMI class or to a database table, and an instance is similar to an instance of the class or to a row in the table. For example, the Win32_LogicalDisk class represents a resource. Win32_LogicalDisk=”C:\” is a specific instance of the resource.

        A Uniform Resource Identifier (URI) contains a prefix and a path to a resource. For example:
        http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk
        http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor

        Cmdlets Supported: Get-Item, Set-Item

    -ResourceURI <String>
        Specifies the Uniform Resource Identifier (URI) that identifies a specific type of resource, such as a disk or a process, on a computer.

        A URI consists of a prefix and a path to a resource. For example:
        http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32_LogicalDisk
        http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_NumericSensor

        Cmdlets Supported: Get-Item

    -RootSDDL <String>
        Specifies the Security Descriptor Definition Language (SDDL) for the access control entry. This identifies the security settings that are used to authorize access to a specified resource URI.

        Cmdlets Supported: Get-Item, Set-Item

    -SDKVersion <String>
        Specifies the version of the WS-Management plug-in SDK. The only valid value is 1.

        Cmdlets Supported: Get-Item, Set-Item

    -Shell <String>
        Specifies the process string for the custom shell. You can specify Environment Variables.

        Cmdlets Supported: Get-Item, Set-Item

    -ShellTimeout <Unsigned Long Integer>
        Specifies the length of time before the shell times out due to inactivity. Specify the time-out value in milliseconds.

        Cmdlets Supported: Get-Item, Set-Item

    -Subject <String>
        Specifies the entity that is identified by the Certificate.

        Cmdlets Supported: Get-Item

    -SupportsOptions <Boolean>
        Specifies whether the plug-in supports the use of options, which are passed within the WSMan:OptionSet header in a request message.

        Cmdlets Supported: Get-Item, Set-Item

    -Transport <String>
        Specifies the transport to use to send and receive WS-Management protocol requests and responses. The value must be either HTTP or HTTPS.

        Note: The Transport value is set when creating a Listener.

        Cmdlets Supported: Get-Item

    -TrustedHosts <String>
        List of remote computers that are connected to the local computer through a trusted network connection. Requests are allowed to be sent to computers specified in this list when using an authentication scheme and transport that does not allow the client to authenticate the service, such as Basic authentication over HTTP.

        If a server is specified in TrustedHosts, the client does not authenticate the server’s identity, leaving it vulnerable to man-in-the-middle attacks. You should only specify hostnames when the network connection is safe from malicious users, such as in a Domain Environment.

        The specified host names can be either Domain Name System (DNS) names or IP addresses. The following values are valid:

        — Blank: No hosts are trusted.

        — The asterisk “*” character: All hosts are trusted.

        A list of host name patterns separated by commas (,) The host name patterns must be formatted as follows:

        — A string that starts with the wildcard character (*). The string must contain at least two characters. All the hosts that share the suffix are trusted.

        — A string that ends with the wildcard character (*). The string must contain at least two characters. All the hosts that share the prefix are trusted.

        — All NetBIOS names are trusted (for example, strings that do not contain a period).

        — A string without the wildcard character (*): The host named by the string is trusted.

        Note: When the TrustedHosts value is set with the Set-Item cmdlet, the Set-Item cmdlet supports an additional parameter -Concatenate. The following example will append a new value (*.domain2.com) to the old value stored in TrustedHost:

         Set-Item .\TrustedHosts *.domain2.com -Concatenate -Force

        Cmdlets Supported: Clear-Item, Get-Item, Set-Item

    -URI <String>
        Identifies the URI for which access is authorized based on the value of the Sddl parameter.

        Cmdlets Supported: Get-Item

    -URLPrefix <String>
        A URL prefix on which to accept HTTP or HTTPS requests. This is a string containing only the characters a-z, A-Z, 9-0, underscore (_) and backslash (/). The string must not start with or end with a backslash (/). For example, if the computer name is SampleComputer, the WS-Management client would specify http://SampleMachine/URLPrefix in the destination address.

        Cmdlets Supported: Clear-Item, Get-Item, Set-Item

    -UserName <String>
        Specifies the user name for a local account or for a domain account. It cannot have a value of NULL.

        The client can specify the credentials to use when creating a shell on a computer. The user name must be specified in the domain\user_name format for a domain account. The user name must be specified in the server_name\user_name format for a local account on a server computer.

        If this structure is used, it must have both the username and password fields specified . It can be used with Basic, Digest, Negotiate, or Kerberos authentication. The client must explicitly specify the credentials when either Basic or Digest authentication is used.

        Cmdlets Supported: Get-Item, Set-Item

    -Value <String>
        Specifies the value of an initialization parameter, which is a plug-in-specific value that is used to specify configuration options.

        Cmdlets Supported: Get-Item, Set-Item

    -XMLRenderingType <String>
        Specifies the format in which XML is passed to plug-ins through the WSMan_DATA object. The following are valid values:

        Text: Incoming XML data is contained in a WSMan_DATA_TYPE_TEXT structure, which represents the XML as a PCWSTR memory buffer.

        XMLReader: Incoming XML data is contained in a WSMan_DATA_TYPE_WS_XML_READER structure, which represents the XML as an XmlReader object, which is defined in the WebServices.h header file.

        Cmdlets Supported: Get-Item, Set-Item

    -xmlns <String>
        A string that specifies specifies a Uniform Resource Name (URN) that uniquely identifies the namespace.

        Cmdlets Supported: Get-Item, Set-Item

    -lang <String>
        A string that specifies a language, or a language-region with language and region separated by a hyphen.

        Cmdlets Supported: Get-Item, Set-Item

    -HTTP <Short Integer>
        Specifies the port that the client will use when HTTP is used. By default, HTTP uses port 80. You can specify any value from 1 through 65535.

        Cmdlets Supported: Get-Item, Set-Item

    -HTTPS <Short-Integer>
        Specifies the port that the client will use when HTTPS is used. By default, HTTPS uses port 443. You can specify any value from 1 through 65535.

        Cmdlets Supported: Get-Item, Set-Item

    -MaxShellRunTime <Unsigned Long Integer>
        Note: This value is deprecated and the value is no longer used.

        Cmdlets Supported: Get-Item

    -MaxShellRunTime <Unsigned Long Integer>
        Note: This value is deprecated and should not be used.

        Cmdlets Supported: Get-Item

NOTES

RELATED LINKS

about_WS-Management_Cmdlets

TOPIC
    about_WS-Management_Cmdlets

SHORT DESCRIPTION
    Provides an overview of Web Services for Management (WS-Management) as
    background for using the WS-Management cmdlets in Windows PowerShell.

LONG DESCRIPTION
    This topic provides an overview of Web Services for Management
    (WS-Management) as background for using the WS-Management cmdlets in
    Windows PowerShell. This topic also provides links to more information
    about WS-Management. The Microsoft implementation of WS-Management is also
    known as Windows Remote Management (WinRM).

About WS-Management

     Windows Remote Management is the Microsoft implementation
     of the WS-Management protocol, a standard SOAP-based, firewall-friendly
     protocol that allows hardware and operating systems from different
     vendors to interoperate. The WS-Management protocol specification
     provides a common way for systems to access and exchange management
     information across an information technology (IT) infrastructure.
     WS-Management and Intelligent Platform Management Interface (IPMI),
     along with the Event Collector, are components of the Windows Hardware
     Management features.

     The WS-Management protocol is based on the following standard Web service
     specifications: HTTPS, SOAP over HTTP (WS-I profile), SOAP 1.2,
     WS-Addressing, WS-Transfer, WS-Enumeration, and WS-Eventing.

WS-Management and WMI

     WS-Management can be used to retrieve data exposed by Windows Management
     Instrumentation (WMI). You can obtain WMI data with scripts or
     applications that use the WS-Management Scripting API or through the
     WinRM command-line tool. WS-Management supports most of the familiar WMI
     classes and operations, including embedded objects. WS-Management can
     leverage WMI to collect data about resources or to manage resources on a
     Windows-based computers. That means that you can obtain data
     about objects such as disks, network adapters, services, or processes
     in your enterprise through the existing set of WMI classes. You can also
     access the hardware data that is available from the standard WMI IPMI
     provider.

WS-Management Windows PowerShell Provider

     The WS-Management provider provides a hierarchical view into the
     available WS-Management configuration settings. The provider allows you
     to explore and set the various WS-Management configuration options.

WS-Management Configuration

     If WS-Management is not installed and configured, Windows PowerShell
     remoting is not available, the WS-Management cmdlets do not run,
     WS-Management scripts do not run, and the WS-Management provider cannot
     perform data operations. The WS-Management command-line tool, WinRM,
     and event forwarding also depend on the WS-Management configuration.

WS-Management Cmdlets

     WS-Management Functionality is implemented in Windows PowerShell through
     a module that contains a set of cmdlets and the WS-Management provider.
     You can use these cmdlets to complete the end-to-end tasks necessary
     to manage WS-Management settings on local and remote computers.

     The following WS-Management cmdlets are available.

     Connection Cmdlets

     — Connect-WSMan: Connects the local computer to the WS-Management
        (WinRM) service on a remote computer.

     — Disconnect-WSMan: Disconnects the local computer from the WS-Management
        (WinRM) service on a remote computer.

     Management-Data Cmdlets

     — Get-WSManInstance: Displays management information for a resource
        instance that is specified by a resource URI.

     — Invoke-WSManAction: Invokes an action on the target object that
        is specified by the resource URI and by the selectors.

     — New-WSManInstance: Creates a new management resource instance.

     — Remove-WSManInstance: Deletes a management resource instance.

     — Set-WSManInstance: Modifies the management information that is
        related to a resource.

     Setup and Configuration Cmdlets

     — Set-WSManQuickConfig: Configures the local computer for remote
        management. You can use the Set-WSManQuickConfig cmdlet to configure
        WS-Management to allow remote connections to the WS-Management (WinRM)
        service. The Set-WSManQuickConfig cmdlet performs the following
        operations:

    – It determines whether the WS-Management (WinRM) service is running.
         If the WinRM service is not running, the Set-WSManQuickConfig cmdlet
         starts the service.

    – It sets the WS-Management (WinRM) service startup type to automatic.

    – It creates a listener that accepts requests from any IP address.
         The default transport protocol is HTTP.

    – It enables a firewall exception for WS-Management traffic.

    Note: To run this cmdlet in Windows Vista, Windows Server 2008, and
             later versions of Windows, you must start Windows PowerShell
             with the “Run as administrator” option.

     — Test-WSMan: Verifies that WS-Management is installed and configured.
        The Test-WSMan cmdlet tests whether the WS-Management (WinRM)
        service is running and configured on a local or remote computer.

     — Disable-WSManCredSSP: Disables CredSSP authentication on a client
        computer.

     — Enable-WSManCredSSP: Enables CredSSP authentication on a client
        computer.

     — Get-WSManCredSSP: Gets the CredSSP-related configuration for a
        client computer.

     WS-Management-Specific Cmdlets

     — New-WSManSessionOption: Creates a WSManSessionOption object to use as
        input to one or more parameters of a WS-Management cmdlet.

Additional WS-Management Information

    For more information about WS-Management, see the following topics in the
    MSDN (Microsoft Developer Network) library.

     “Windows Remote Management”
     http://go.microsoft.com/fwlink/?LinkId=142321

     “About Windows Remote Management”
     http://go.microsoft.com/fwlink/?LinkId=142322

     “Installation and Configuration for Windows Remote Management”
     http://go.microsoft.com/fwlink/?LinkId=142323

     “Windows Remote Management Architecture”
     http://go.microsoft.com/fwlink/?LinkId=142324

     “WS-Management Protocol”
     http://go.microsoft.com/fwlink/?LinkId=142325

     “Windows Remote Management and WMI”
     http://go.microsoft.com/fwlink/?LinkId=142326

     “Resource URIs”
     http://go.microsoft.com/fwlink/?LinkId=142327

     “Remote Hardware Management”
     http://go.microsoft.com/fwlink/?LinkId=142328

     “Events”
     http://go.microsoft.com/fwlink/?LinkId=142329

SEE ALSO
    Online version: http://go.microsoft.com/fwlink/?LinkId=142331
    Connect-WSMan
    Disable-WSManCredSSP
    Disconnect-WSMan
    Enable-WSManCredSSP
    Get-WSManCredSSP
    Get-WSManInstance
    Invoke-WSManAction
    New-WSManInstance
    Remove-WSManInstance
    Set-WSManInstance
    Set-WSManQuickConfig
    Set-WSManSessionOption
    Test-WSMan

KEYWORDS
    about_WSMAN about_WinRM