Tag Archives: PSProvider

Remove-PSDrive

February 26, 2014 Adam

SYNOPSIS
Removes a Windows PowerShell drive from its location.

SYNTAX
Remove-PSDrive [-LiteralName] <string[]> [-Force] [-PSProvider <string[]>] [-Scope <string>] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

Remove-PSDrive [-Name] <string[]> [-Force] [-PSProvider <string[]>] [-Scope <string>] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The Remove-PSDrive cmdlet deletes Windows PowerShell drives that you created by using New-PSDrive.

Remove-PSDrive cannot delete Windows drives or mapped network drives created by using other methods and it cannot delete the current working drive.

PARAMETERS
-Force [<SwitchParameter>]
Allows the cmdlet to remove the current Windows PowerShell drive.

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

-LiteralName <string[]>
Specifies the name of the Windows PowerShell drive.

The value of LiteralName is used exactly as typed. No characters are interpreted as wildcards. If the name includes escape characters, enclose it in single quotation marks (‘). Single quotation marks instruct Windows PowerShell not to interpret any characters as escape sequences.

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

-Name <string[]>
Specifies the names of the Windows PowerShell drives to remove. Do not type a colon (:) after the drive name.

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

-PSProvider <string[]>
Removes all of the Windows PowerShell drives associated with the specified Windows PowerShell provider.

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

-Scope <string>
Accepts an index that identifies the scope from which the drive is being removed.

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

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

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

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

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

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

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

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

INPUTS
System.Management.Automation.PSDriveInfo
You can pipe a drive object to Remove-PSDrive.

OUTPUTS
None
This cmdlet does not return any output.

NOTES

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

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

C:\PS>Remove-PSDrive -Name smp

    Description
    ———–
    This command removes a Windows PowerShell drive named “smp”.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113376
    about_providers
    Get-PSDrive
    New-PSDrive

cmdlet, New, PSDrive

New-PSDrive

February 26, 2014 Adam

NAME
New-PSDrive

SYNOPSIS
Creates a Windows PowerShell drive in the current session.

SYNTAX
New-PSDrive [-Name] <string> [-PSProvider] <string> [-Root] <string> [-Credential <PSCredential>] [-Description <string>] [-Scope <string>] [-Confirm] [-WhatIf] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The New-PSDrive cmdlet creates a Windows PowerShell drive that is “mapped” to or associated with a location in a data store, such as a network drive, a directory on the local computer, or a Registry key.

You can use the Windows PowerShell drives that you create to access data in the associated data store, just like you would do with any mapped drive. You can change locations into the drive (using “Set-Location“, “cd”, or “chdir”) and access the contents of the drive (using “Get-Item“, “Get-ChildItem“, or “dir”).

However, the Windows PowerShell drives are known only to Windows PowerShell. You cannot access them by using Windows Explorer, Windows Management Instrumentation (WMI), Component Object Model (COM), or the Microsoft .NET Framework, or by using tools such as Net Use.

Windows PowerShell drives exist only in the current Windows PowerShell session. To make the drive persistent, you can export the session to which you have added the drive, or you can save a New-PSDrive command in your Windows PowerShell profile.

To delete a drive that was created by New-PSDrive, use the Remove-PSDrive cmdlet.

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

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

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

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

-Description <string>
Specifies a brief text description of the drive. Type any string.

To see the descriptions of all of the Windows PowerShell drives on your system, type “Get-PSDrive | format name, description”. To see the description of a particular Windows PowerShell drives, type “(Get-PSDrive <DriveName>).description”.

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

-Name <string>
Specifies a name for the new drive. You can use any valid string for the name. You are not limited to drive letters. Windows PowerShell drives names are case-sensitive.

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

-PSProvider <string>
Specifies the Windows PowerShell provider that supports drives of this type.

For example, if the Windows PowerShell drives is associated with a network share or file system directory, the Windows PowerShell provider is “FileSystem”. If the Windows PowerShell drive is associated with a Registry key, the provider is “Registry”.

To see a list of the providers in your Windows PowerShell session, type “Get-PSProvider“.

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

-Root <string>
Specifies the data store location that the Windows PowerShell drive is mapped to.

For example, specify a network share (such as \\Server01\Public), a local directory (such as C:\Program Files), or a Registry key (such as HKLM:\Software\Microsoft).

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

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

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

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

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

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

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

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

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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
System.Management.Automation.PSDriveInfo

NOTES

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

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

C:\PS>New-PSDrive -Name P -PSProvider FileSystem -Root \\Server01\Public

    Name     Provider     Root
    —-     ——–     —-
    P         FileSystem    \\Server01\Public

    Description
    ———–
    This command creates a Windows PowerShell drive that Functions like a mapped network drive in Windows. The command creates a Windows PowerShell drive named P: that is mapped to the \\Server01\Public network share.

It uses the Name parameter to specify a name for the drive, the PSProvider parameter to specify the Windows PowerShell FileSystem provider, and the Root parameter to specify the network share.

When the command completes, the contents of the \\Server01\Public share appear in the P: drive. To see them, type: “dir p:”.

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

C:\PS>New-PSDrive -Name MyDocs -PSProvider FileSystem -Root “C:\Documents and Settings\User01\My Documents” -Description “Maps to my My Documents folder.”

    Name     Provider     Root
    —-     ——–     —-
    MyDocs     FileSystem    C:\Documents and Settings\User01\My Documents

    Description
    ———–
    This command creates a Windows PowerShell drive that provides quick access to a local directory. It creates a drive named MyDocs: that is mapped to the
    “C:\Documents and Settings\User01\My Documents” directory on the local computer.

It uses the Name parameter to specify a name for the drive, the PSProvider parameter to specify the Windows PowerShell FileSystem provider, the Root parameter to specify the path to the My Documents folder, and the Description parameter to create a description of the drive.

When the command completes, the contents of the My Documents folder appear in the MyDocs: drive. To see them, type: “dir mydocs:”.

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

C:\PS>New-PSDrive -Name MyCompany -PSProvider Registry -Root HKLM:\Software\MyCompany

    Name     Provider     Root
    —-     ——–     —-
    MyCompany Registry     HKEY_LOCAL_MACHINE\Software\MyCo…

    Description
    ———–
    This command creates a Windows PowerShell drive that provides quick access to a frequently checked Registry key. It creates a drive named MyCompany that is mapped to the HKLM\Software\MyCompany Registry key.

It uses the Name parameter to specify a name for the drive, the PSProvider parameter to specify the Windows PowerShell Registry provider, and the Root parameter to specify the Registry key.

When the command completes, the contents of the MyCompany key appear in the MyCompany: drive. To see them, type: “dir MyCompany:”.

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

C:\PS>New-PSDrive -Name PsDrive -PSProvider FileSystem -Root \\Server01\Public

C:\PS> $drive = New-Object -com wscript.network
C:\PS> $drive.MapNetworkDrive(“X:”, “\\Server01\Public”)

C PS:\> Get-PSDrive public, x

    Name     Provider     Root
    —-     ——–     —-
    PsDrive    FileSystem    \\Server01\public
    X         FileSystem    X:\

C:\PS>Get-PSDrive psdrive, x | Get-Member

     TypeName: System.Management.Automation.PSDriveInfo
    Name                MemberType Definition
    —-                ———- ———-
    CompareTo         Method     System.Int32 CompareTo(PSDriveInfo drive),
    Equals             Method     System.Boolean Equals(Object obj),
    GetHashCode         Method     System.Int32 GetHashCode()
    …

    C:\PS> net use
    Status     Local     Remote                    Network
    —————————————————————————
                 X:        \\server01\public         Microsoft Windows Network

    C:\PS> Get-WmiObject win32_logicaldisk | ft deviceid
    deviceid
    ——–
    C:
    D:
    X:

    C:\PS> Get-WmiObject win32_networkconnection
    LocalName                     RemoteName                    ConnectionState             Status
    ———                     ———-                    —————             ——
    X:                            \\products\public             Disconnected                 Unavailable

    Description
    ———–
    This example shows the difference between a Windows drive that is mapped to a network share and a Windows PowerShell drive that is mapped to the same network share.

The first command uses the New-PSDrive cmdlet to create a Windows PowerShell drive called PSDrive: that is mapped to the \\Server01\Public network share.

The second set of commands uses the New-Object cmdlet to create a Wscript.Network COM object and then use its MapNetworkDrive method to map the \\Server01\Public network share to the X: drive on the local computer.

Now, you can examine the two drives. Using a Get-PSDrive drive command, the drives appear to be the same, although the network share name appears only in the root of the PSDrive: drive.

Sending the drive objects to Get-Member shows that they have the same object type, System.Management.Automation.PSDriveInfo.

However, a “net use” command, a Get-WmiObject command to the Win32_LogicalDisk class, and a Get-WmiObject command to the Win32_NetworkConnection class find only the X: drive that was created by using the Wscript.Network object. That is because Windows PowerShell drives are known only to Windows PowerShell.

If you close the Windows PowerShell session and then open a new one, the PSDrive: drive is gone, and the X: drive persists.

Therefore, when deciding which method to use to map network drives, consider how you will use the drive, whether it needs to be persistant, and whether the drive needs to be visible to other Windows features.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113357
    about_providers
    Get-PSDrive
    Remove-PSDrive

cmdlet, Get, PSProvider

Get-PSProvider

February 26, 2014 Adam

NAME
Get-PSProvider

SYNOPSIS
Gets information about the specified Windows PowerShell provider.

SYNTAX
Get-PSProvider [[-PSProvider] <string[]>] [<CommonParameters>]

DESCRIPTION
The Get-PSProvider cmdlet gets the Windows PowerShell providers in the current session. You can get a particular drive or all drives in the session.

Windows PowerShell providers let you access a variety of data stores as though they were file system drives. For information about Windows PowerShell providers, see about_providers.

PARAMETERS
-PSProvider <string[]>
Specifies the name or names of the Windows PowerShell providers about which to retrieve information.

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

INPUTS
None
You cannot pipe objects to this cmdlet.

OUTPUTS
System.Management.Automation.ProviderInfo
Get-PSProvider returns objects that represent the Windows PowerShell providers in the session.

NOTES

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

C:\PS>Get-PSProvider

    Description
    ———–
    This command displays a list of all available Windows PowerShell providers.

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

C:\PS>Get-PSProvider f*, r* | Format-List

    Description
    ———–
    This command displays a list of all Windows PowerShell providers with names that begin with the letter “f” or “r”.

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

C:\PS>Get-PSProvider | Format-Table name, module, pssnapin -auto

    Name        Module     PSSnapIn
    —-        ——     ——–
    Test        TestModule
    WSMan                    Microsoft.WSMan.Management
    Alias                    Microsoft.PowerShell.Core
    Environment             Microsoft.PowerShell.Core
    FileSystem             Microsoft.PowerShell.Core
    Function                 Microsoft.PowerShell.Core
    Registry                 Microsoft.PowerShell.Core
    Variable                 Microsoft.PowerShell.Core
    Certificate             Microsoft.PowerShell.Security

C:\PS> Get-PSProvider | where {$_.pssnapin -eq “Microsoft.PowerShell.Security”}

    Name            Capabilities     Drives
    —-            ————     ——
    Certificate     ShouldProcess     {cert}

    Description
    ———–
    These commands find the Windows PowerShell snap-ins or modules that added providers to your session. All Windows PowerShell elements, including providers, originate in a snap-in or in a module.

These commands use the PSSnapin and Module properties of the ProviderInfo object that Get-PSProvider returns. The values of these properties contain the name of the snap-in or module that adds the provider.

The first command gets all of the providers in the session and formats them in a table with the values of their Name, Module, and PSSnapin properties.

The second command uses the Where-Object cmdlet to get the providers that come from the Microsoft.PowerShell.Security snap-in.

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

cmdlet, Get, PSDrive

Get-PSDrive

February 26, 2014 Adam

NAME
Get-PSDrive

SYNOPSIS
Gets the Windows PowerShell drives in the current session.

SYNTAX
Get-PSDrive [-LiteralName] <string[]> [-PSProvider <string[]>] [-Scope <string>] [-UseTransaction] [<CommonParameters>]

Get-PSDrive [[-Name] <string[]>] [-PSProvider <string[]>] [-Scope <string>] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The Get-PSDrive cmdlet gets the Windows PowerShell drives in the current session. You can get a particular drive or all drives in the console.

Get-PSDrive gets the following drives:

— Windows logical drives on the computer, including drives mapped to network shares.

— Drives exposed by Windows PowerShell providers (such as the Certificate:, Function:, and Alias: drives) and the HKLM: and HKCU: drives that are exposed by the Windows PowerShell Registry provider.

— Drives that you create by using New-PSDrive.

Get-PSDrive does not get Windows mapped drives that are added or created after the Windows PowerShell console is opened.

PARAMETERS
-LiteralName <string[]>
Specifies the name of the Windows PowerShell drive.

The value of LiteralName is used exactly as it is typed. No characters are interpreted as wildcards. If the name includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.

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

-Name <string[]>
Gets only the specified drives. Type the drive name or letter without a colon (:).

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

-PSProvider <string[]>
Gets only the drives supported by the specified Windows PowerShell provider. Type the name of a provider, such as FileSystem, Registry, or Certificate.

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

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

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

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

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

INPUTS
None
You cannot pipe objects to Get-PSDrive.

OUTPUTS
System.Management.Automation.PSDriveInfo
Get-PSDrive returns objects that represent the Windows PowerShell drives in the session.

NOTES

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

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

C:\PS>Get-PSDrive

    Name     Provider     Root
    —-     ——–     —-
    Alias     Alias
    C         FileSystem    C:\
    cert     Certificate \
    D         FileSystem    D:\
    Env        Environment
    Function Function
    HKCU     Registry     HKEY_CURRENT_USER
    HKLM     Registry     HKEY_LOCAL_MACHINE
    Variable Variable
    X         FileSystem    X:\

    Description
    ———–
    This command gets the Windows PowerShell drives in the current session.

The output shows the hard drive (C:) and CD-ROM drive (D:) on the computer, the drives exposed by the Windows PowerShell providers (Alias:, Cert:, Env:, Function:, HKCU:, HKLM:, and Variable:), and a drive mapped to a network share (X:).

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

C:\PS>Get-PSDrive d

    Name     Provider     Root
    —-     ——–     —-
    D         FileSystem    D:\

    Description
    ———–
    This command displays the D: drive on the computer. Note that the drive letter is not followed by a colon.

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

C:\PS>Get-PSDrive -PSProvider FileSystem

    Name     Provider     Root
    —-     ——–     —-
    C         FileSystem    C:\
    D         FileSystem    D:\
    X         FileSystem    X:\
    Y         FileSystem    \\Server01\Public
    Z         FileSystem    C:\Windows\System32

    Description
    ———–
    This command displays all of the drives that are supported by the Windows PowerShell FileSystem provider. This includes fixed drives, logical partitions, mapped network drives, and drives that you create by using New-PSDrive that are mapped to the file system drives.

This example shows that drives created by New-PSDrive have the name of the mapped location in the value of the Root property. Windows drives just have the root of the drive letter.

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

    C:\PS>if (!(Get-PSDrive X)) {
        New-PSDrive -Name X -PSProvider Registry -root HKLM:\Network
    }
    else { Write-Host “The X: drive is already in use.” }

    Description
    ———–
    This command checks to see whether the X drive is already in use as the Windows PowerShell drive name. If it is not, the command uses the New-PSDrive cmdlet to create a Windows PowerShell drive that is mapped to the HKLM:\Network Registry key.

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

C:\PS>Get-PSDrive -provider FileSystem

C:\PS> Get-PSDrive -provider FileSystem

C:\PS> net use
New connections will be remembered.

    Status     Local     Remote                    Network
    ——————————————————————————-
                 X:        \\Server01\Public         Microsoft Windows Network

C:\PS> [System.IO.DriveInfo]::getdrives()

    Name             : C:\
    DriveType         : Fixed
    DriveFormat        : NTFS
    IsReady            : True
    AvailableFreeSpace : 39831498752
    TotalFreeSpace     : 39831498752
    TotalSize         : 79900368896
    RootDirectory     : C:\
    VolumeLabel        :
    Name             : D:\
    DriveType         : CDRom
    DriveFormat        :
    IsReady            : False
    AvailableFreeSpace :
    TotalFreeSpace     :
    TotalSize         :
    RootDirectory     : D:\
    VolumeLabel        :
    Name             : X:\
    DriveType         : Network
    DriveFormat        : NTFS
    IsReady            : True
    AvailableFreeSpace : 36340559872
    TotalFreeSpace     : 36340559872
    TotalSize         : 36413280256
    RootDirectory     : X:\
    VolumeLabel        : D_Drive

C:\PS> Get-WmiObject win32_logicaldisk

    DeviceID     : C:
    DriveType    : 3
    ProviderName :
    FreeSpace    : 39831252992
    Size         : 79900368896
    VolumeName :
    DeviceID     : D:
    DriveType    : 5
    ProviderName :
    FreeSpace    :
    Size         :
    VolumeName :
    DeviceID     : X:
    DriveType    : 4
    ProviderName : \\server01\public
    FreeSpace    : 36340559872
    Size         : 36413280256
    VolumeName : D_Drive

    C:\PS> Get-WmiObject win32_networkconnection
    LocalName                     RemoteName
    ————–             ————
    x:                            \\server01\public

    Description
    ———–
    This example compares the types of file system drives that are displayed by Get-PSDrive to those displayed by using other methods. This example demonstrates different ways to display drives in Windows PowerShell, and it shows that the drives created by using New-PSDrive are accessible only in Windows PowerShell.

The first command uses Get-PSDrive to get all of the file system drives in the Windows PowerShell console. This includes the fixed drives (C: and D:), the mapped network drive (X:), and two Windows PowerShell drives (Y: and Z:) that were created by using New-PSDrive.

A “net use” command, which displays Windows mapped network drives, displays only the X drive. It does not display drives that are created by New-PSDrive. It shows that the X: drive is also mapped to \\Server01\Public.

The third command uses the GetDrives method of the Microsoft .NET Framework System.IO.DriveInfo class. This command gets the Windows file system drives, including drive X:, but it does not get the drives created by New-PSDrive.

The fourth command uses the Get-WmiObject cmdlet to display the instances of the Win32_LogicalDisk class. It returns the C:, D:, and X: drives, but not the drives created by New-PSDrive.

The last command uses the Get-WmiObject cmdlet to display the instances of the Win32_NetworkConnection class. Like “net use”, it returns only the X: drive.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113327
    about_providers
    New-PSDrive
    Remove-PSDrive
    Get-Help
    Get-Command
    Get-Member

cmdlet, Get, Location

Get-Location

February 26, 2014 Adam

NAME
Get-Location

SYNOPSIS
Gets information about the current working location.

SYNTAX
Get-Location [-PSDrive <string[]>] [-PSProvider <string[]>] [-UseTransaction] [<CommonParameters>]

Get-Location [-Stack] [-StackName <string[]>] [-UseTransaction] [<CommonParameters>]

DESCRIPTION
The Get-Location cmdlet gets an object that represents the current directory, much like the pwd (print working directory) command.

When you move between Windows PowerShell drives, Windows PowerShell retains your location in each drive. You can use Get-Location to find your location in each drive.

You can also use Get-Location to get the current directory at run time and use it in Functions and scripts, such as in a Function that displays the current directory in the Windows PowerShell prompt.

If you use the Push-Location cmdlet to add locations to a path stack, you can use the Stack parameter of Get-Location to display the current stack.

PARAMETERS
-PSDrive <string[]>
Gets the current location in the specified Windows PowerShell drive.

For example, if you are in the Certificate: drive, you can use this parameter to find your current location in the C: drive.

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

-PSProvider <string[]>
Gets the current location in the drive supported by the specified Windows PowerShell provider.

If the specified provider supports more than one drive, Get-Location returns the location on the most recently accessed drive.

For example, if you are in the C: drive, you can use this parameter to find your current location in the drives of the Windows PowerShell Registry provider.

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

-Stack [<SwitchParameter>]
Displays the locations in the default path stack.

To add paths to the default stack, use the Push-Location cmdlet.

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

-StackName <string[]>
Displays the locations in the specified path stacks.

To create path stacks, use the Push-Location cmdlet.

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

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

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

INPUTS
None
You cannot pipe input to this cmdlet.

OUTPUTS
PathInfo objects or StackInfo objects
If you use the Stack or StackName parameters, Get-Location returns a StackInfo object. Otherwise, it returns a PathInfo object.

NOTES

Locations can be stored on a stack. The Push-Location cmdlet adds a location to the top of the stack. The Pop-Location cmdlet gets the location at the top of the stack.

The ways that the PSProvider, PSDrive, Stack, and StackName parameters interact depends on the provider. Some combinations will result in errors, such as specifying both a drive and a provider that does not expose that drive. If no parameters are specified, Get-Location returns the PathInfo object for the provider that contains the current working location.

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

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

C:\PS>Get-Location

    Path
    —-
    C:\WINDOWS

    Description
    ———–
    This command displays your location in the current Windows PowerShell drive.

For example, if you are in the Windows directory of the C: drive, it displays the path to that directory.

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

C:\PS>Set-Location

    Description
    ———–
    These commands demonstrate the use of Get-Location to display your current location in different Windows PowerShell drives.

The first command uses the Set-Location cmdlet to set the current location to the Windows subdirectory of the C: drive.

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

The second command uses the Set-Location cmdlet to change the location to the HKLM:\Software\Microsoft Registry key. When you change to a location in the HKLM: drive, Windows PowerShell retains your location in the C: drive.

PS C:\WINDOWS> Set-Location HKLM:\Software\Microsoft
PS HKLM:\Software\Microsoft>

The third command uses the Set-Location cmdlet to change the location to the “HKCU:\Control Panel\Input Method” Registry key.

PS HKLM:\Software\Microsoft> Set-Location ‘HKCU:\Control Panel\Input Method’
PS HKCU:\Control Panel\Input Method>

The fourth command uses the Get-Location cmdlet to find the current location on the C: drive. It uses the PSDrive parameter to specify the drive.

        PS HKCU:\Control Panel\Input Method> Get-Location -PSDrive c
        Path
        —-
        C:\WINDOWS

The fifth command uses the Set-Location cmdlet to return to the C: drive. Even though the command does not specify a subdirectory, Windows PowerShell returns you to the saved location.

PS HKCU:\Control Panel\Input Method> Set-Location C:
PS C:\WINDOWS>

The sixth command uses the Get-Location cmdlet to find the current location in the drives supported by the Windows PowerShell Registry provider. Get-Location returns the location of the most recently accessed Registry drive, HKCU:.

        PS C:\WINDOWS> Get-Location -PSProvider Registry
        Path
        —-
        HKCU:\Control Panel\Input Method

To see the current location in the HKLM: drive, you need to use the PSDrive parameter to specify the drive. The seventh command does just this:

        PS C:\WINDOWS> Get-Location -PSDrive HKLM
        Path
        —-
        HKLM:\Software\Microsoft

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

C:\PS>Set-Location

    Description
    ———–
    These commands show how to use the Stack and StackName parameters of Get-Location to list the paths in the default and alternate path stacks.

The first command sets the current location to the Windows directory on the C: drive.

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

The second command uses the Push-Location cmdlet to push the current location (C:\Windows) onto the path stack and change to the System32 subdirectory. Because no stack is specified, the current location is pushed onto the default stack.
C:\WINDOWS>Push-Location System32

The third command pushes the current location (C:\Windows\System32) onto the Stack2 stack and changes the location to the WindowsPowerShell subirectory.

C:\Windows\System32>Push-Location WindowsPowerShell -stack Stack2

The fourth command uses the Get-Location cmdlet to get the paths on the default path stack.

C:\WINDOWS\system32\WindowsPowerShell>Get-Location -stack

        Path
        —-
        C:\WINDOWS

The last command uses the StackName parameter of Get-Location to get the paths on the Stack2 stack.

C:\WINDOWS\system32\WindowsPowerShell>Get-Location -stackname Stack2

        Path
        —-
        C:\WINDOWS\system32

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

C:\PS>function prompt { ‘PowerShell: ‘ + (Get-Location) + ‘> ‘}

PowerShell: C:\WINDOWS>

    Description
    ———–
    This example shows how to customize the Windows PowerShell prompt. The Function that defines the prompt includes a Get-Location command, which is run whenever the prompt appears in the console.

The format of the default Windows PowerShell prompt is defined by a special Function called “prompt”. You can change the prompt in your console by creating a new Function called “prompt”.

To see the current prompt Function, type the following command:

Get-Content Function:prompt

The command begins with the “function” keyword followed by the Function name, “prompt”. The Function body appears within braces ( {} ).

This command defines a new prompt that begins with the string “PowerShell: “. To append the current location, it uses a Get-Location command, which runs when the prompt Function is called. The prompt ends with the string “> “.

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