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

    <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
    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