New-PSDrive

Syntax

New-PSDrive
   [-Name] <String>
   [-PSProvider] <String>
   [-Root] <String>
   [-Description <String>]
   [-Scope <String>]
   [-Persist]
   [-Credential <PSCredential>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

The New-PSDrive cmdlet creates temporary and persistent drives that are 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, and persistent Windows mapped network drives that are associated with a file system location on a remote computer.

Temporary drives exist only in the current PowerShell session and in sessions that you create in the current session. They can have any name that is valid in PowerShell and can be mapped to any local or remote resource. You can use temporary PowerShell drives to access data in the associated data store, just as you would do with any mapped network drive. You can change locations into the drive, by using Set-Location, and access the contents of the drive by using Get-Item or Get-ChildItem.

Because temporary drives are known only to PowerShell, you can't access them by using File Explorer, Windows Management Instrumentation (WMI), Component Object Model (COM), Microsoft .NET Framework, or with tools such as net use.

The following features were added to New-PSDrive in PowerShell 3.0:

• Mapped network drives. You can use the Persist parameter of New-PSDrive to create Windows mapped network drives. Unlike temporary PowerShell drives, Windows mapped network drives aren't session-specific. They're saved in Windows and they can be managed by using standard Windows tools, such as File Explorer and net use. Mapped network drives must have a drive-letter name and be connected to a remote file system location. When your command is scoped locally, no dot-sourcing, the Persist parameter doesn't persist the creation of a PSDrive beyond the scope in which the command is running. If you're running New-PSDrive inside a script, and you want the drive to persist indefinitely, you must dot-source the script. For best results, to force a new drive to persist indefinitely, add the Scope parameter to your command, and set its value to Global. For more information about dot-sourcing, see about_Scripts.
• External drives. When an external drive is connected to the computer, PowerShell automatically adds a PSDrive to the file system that represents the new drive. You don't have to restart PowerShell. Similarly, when an external drive is disconnected from the computer, PowerShell automatically deletes the PSDrive that represents the removed drive.
• Credentials for Universal Naming Convention (UNC) paths.

When the value of the Root parameter is a UNC path, such as \\Server\Share, the credential specified in the value of the Credential parameter is used to create the PSDrive. Otherwise, Credential isn't effective when you're creating new file system drives.

Some code samples use splatting to reduce the line length and improve readability. For more information, see about_Splatting.

Examples

Example 1: Create a temporary drive mapped to a network share

This example creates a temporary PowerShell drive that's mapped to a network share.

New-PSDrive -Name "Public" -PSProvider "FileSystem" -Root "\\Server01\Public"

Name       Provider      Root
----       --------      ----
Public     FileSystem    \\Server01\Public

New-PSDrive uses the Name parameter to specify PowerShell drive named Public and the PSProvider parameter to specify the PowerShell FileSystem provider. The Root parameter specifies the network share's UNC path.

To view the contents from a PowerShell session: Get-ChildItem -Path Public:

Example 2: Create a temporary drive mapped to a local directory

This example creates a temporary PowerShell drive that provides access to a directory on the local computer.

$parameters = @{
    Name = "MyDocs"
    PSProvider = "FileSystem"
    Root = "C:\Users\User01\Documents"
    Description = "Maps to my My Documents folder."
}
New-PSDrive @parameters

Name        Provider      Root
----        --------      ----
MyDocs      FileSystem    C:\Users\User01\Documents

Splatting creates the parameter keys and values. The Name parameter specifies the drive name, MyDocs. The PSProvider parameter specifies the PowerShell FileSystem provider. Root specifies the local computer's directory. The Description parameter describes the drive's purpose. New-PSDrive uses the splatted parameters to create the MyDocs drive.

To view the contents from a PowerShell session: Get-ChildItem -Path MyDocs:

Example 3: Create a temporary drive for a registry key

This example creates a temporary PowerShell drive that provides access to a registry key. It creates a drive named MyCompany that is mapped to the HKLM:\Software\MyCompany registry key.

New-PSDrive -Name "MyCompany" -PSProvider "Registry" -Root "HKLM:\Software\MyCompany"

Name           Provider      Root
----           --------      ----
MyCompany      Registry      HKLM:\Software\MyCompany

New-PSDrive uses the Name parameter to specify PowerShell drive named MyCompany and the PSProvider parameter to specify the PowerShell Registry provider. The Root parameter specifies the registry location.

To view the contents from a PowerShell session: Get-ChildItem -Path MyCompany:

Example 4: Create a persistent mapped network drive using credentials

This example maps a network drive that's authenticated with a domain service account's credentials. For more information about the PSCredential object that stores credentials and how passwords are stored as a SecureString, see the Credential parameter's description.

$cred = Get-Credential -Credential Contoso\ServiceAccount
New-PSDrive -Name "S" -Root "\\Server01\Scripts" -Persist -PSProvider "FileSystem" -Credential $cred
Net Use

Status       Local     Remote                    Network
---------------------------------------------------------
OK           S:        \\Server01\Scripts        Microsoft Windows Network

The $cred variable stores a PSCredential object that contains the service account's credentials. Get-Credential prompts you to enter the password that's stored in a SecureString.

New-PSDrive creates the mapped network drive by using several parameters. Name specifies the S drive letter that Windows accepts. and Root defines \\Server01\Scripts as the location on a remote computer. Persist creates a Windows mapped network drive that's saved on the local computer. PSProvider specifies the FileSystem provider. Credential uses the $cred variable to get the service account credentials for authentication.

The mapped drive can be viewed on the local computer in PowerShell sessions, File Explorer, and with tools such as net use. To view the contents from a PowerShell session: Get-ChildItem -Path S:

Example 5: Create persistent and temporary drives

This example shows the difference between a persistent mapped network drive and a temporary PowerShell drive that is mapped to the same network share.

If you close the PowerShell session and then open a new session, the temporary PSDrive: isn't available, but the persistent X: drive is available. When deciding which method to use to map network drives, consider how you'll use the drive. For example, whether it has to be persistent, and whether the drive has to be visible to other Windows features.

# Create a temporary PowerShell drive called PSDrive:
# that's mapped to the \\Server01\Public network share.
New-PSDrive -Name "PSDrive" -PSProvider "FileSystem" -Root "\\Server01\Public"

# Use the Persist parameter of New-PSDrive to create the X: mapped network drive,
# which is also mapped to the \\Server01\Public network share.
New-PSDrive -Persist -Name "X" -PSProvider "FileSystem" -Root "\\Server01\Public"

# Now, you can use the Get-PSDrive drive cmdlet to examine the two drives.
# The drives appear to be the same, although the network share name appears only
# in the root of the PSDrive: drive.
Get-PSDrive -Name "PSDrive", "X"

Name       Provider      Root
----       --------      ----

PsDrive    FileSystem    \\Server01\public
X          FileSystem    X:\

# Get-Member cmdlet shows that the drives have the same object type,
# System.Management.Automation.PSDriveInfo.
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()
...

# Net Use and Get-CimInstance for the Win32_LogicalDisk class,
# and Win32_NetworkConnection class find only the persistent X: drive.
# PowerShell temporary drives are known only to PowerShell.
Net Use
Get-CimInstance Win32_LogicalDisk | Format-Table -Property DeviceID
Get-CimInstance Win32_NetworkConnection

Status       Local     Remote                    Network
--------------------------------------------------------
OK           X:        \\contoso-pc\data         Microsoft Windows Network

deviceid
--------
C:
D:
X:

LocalName    RemoteName              ConnectionState          Status
---------    ----------              ---------------          ------
X:           \\products\public       Disconnected             Unavailable

Example 6: Create persistent drive in a script

PSDrives are created in the scope in which the New-PSDrive command is run. When the command is run within a script, the drive mapping is local to the script. When the script exits, the drive is no longer available.

New-PSDrive -Persist -Name "X" -PSProvider "FileSystem" -Root "\\Server01\Public" -Scope Global

To ensure that the drive is available outside of the script to must use the Scope parameter to create the drive in the Global scope.

Parameters

-Confirm

-Credential

-Description

-Name

-Persist

-PSProvider

-Root

-Scope

-WhatIf

Inputs

None

You can't pipeline input to this cmdlet.

Outputs

PSDriveInfo

Notes

New-PSDrive is designed to work with the data exposed by any provider. To list the providers available in your session, use Get-PSProvider. For more information about providers, see about_Providers.

Mapped network drives are specific to a user account. Mapped drives created in elevated sessions or sessions using the credential of another user aren't visible in sessions started using different credentials.

Related Links

• about_Providers
• Get-Credential
• Get-PSDrive
• Remove-PSDrive