PowerShell Logo Small

New-PSDrive



This is the built-in help made by Microsoft for the command 'New-PSDrive', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-23.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

SYNOPSIS

Creates temporary and persistent mapped network drives.

SYNTAX


New-PSDrive [-Name] <String> [-PSProvider] <String> [-Root] <String> [-Credential [<PSCredential>]] [-Description [<String>]] [-InformationAction {SilentlyContinue | Stop |
Continue | Inquire | Ignore | Suspend}] [-InformationVariable [<System.String>]] [-Persist] [-Scope [<String>]] [-Confirm] [-WhatIf] [-UseTransaction [<SwitchParameter>]]
[<CommonParameters>]



Search powershellhelp.space

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 Windows PowerShell session and in sessions that you create in the current session. They can have any name that is valid in Windows
PowerShell and can be mapped to any local or remote resource. You can use temporary Windows PowerShell drives to access data in the associated data store, just like you
would do with any mapped network 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, because temporary drives are known only to Windows PowerShell, you cannot access them by using File Explorer, Windows Management Instrumentation (WMI), Component
Object Model (COM), or the Microsoft .NET Framework, or by using tools such as Net Use.


New features are added to New-PSDrive in Windows PowerShell 3.0.


-- Mapped network drives: You can use the Persist parameter of New-PSDrive to create Windows mapped network drives. Unlike temporary Windows PowerShell drives, Windows
mapped network drives are not session-specific; they are 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 are running New-PSDrive inside of 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.


-- External drives: When an external drive is connected to the computer, Windows PowerShell automatically adds a PSDrive to the file system that represents the new drive.
You do not need to restart Windows PowerShell. Similarly, when an external drive is disconnected from the computer, Windows PowerShell automatically deletes the PSDrive that
represents the removed drive.


-- Credentials for 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, the Credential parameter is not effective when creating new file system drives.



<

RELATED LINKS

Online Version: http://go.microsoft.com/fwlink/p/?linkid=293888
Get-PSDrive
Remove-PSDrive
about_Providers

REMARKS

<

Examples


-------------------------- EXAMPLE 1 --------------------------

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

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



This command creates a temporary 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 --------------------------

PS C:\>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



This command creates a temporary 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 --------------------------

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

Name Provider Root
---- -------- ----
MyCompany Registry HKEY_LOCAL_MACHINE\Software\MyCo...



This command creates a temporary 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 --------------------------

PS C:\>New-PSDrive -Name S -Root \\Server01\Scripts -Persist -PSProvider FileSystem
PS C:\> net use
Status Local Remote Network
---------------------------------------------------------
OK S: \\Server01\Scripts Microsoft Windows Network



This command creates the "S" mapped network drive on the local computer. The "S" drive is mapped to the \\Server01\Scripts network share.

The command uses the New-PSDrive cmdlet to create the mapped network drive. It uses the Persist parameter to create a Windows mapped network drive that is saved on the local
computer.

The command uses the Name parameter to specify a letter name that Windows accepts and the Root parameter to specify a location on a remote computer. It uses the PSProvider
parameter to specify the FileSystem provider.

The resulting drive can be viewed in other Windows PowerShell sessions on the local computer, in Windows Explorer, and in other tools, such as Net Use.






-------------------------- EXAMPLE 5 --------------------------

The first command uses the New-PSDrive cmdlet to create a temporary Windows PowerShell drive called PSDrive: that is mapped to the \\Server01\Public network share.
PS C:\>New-PSDrive -Name PSDrive -PSProvider FileSystem -Root \\Server01\Public

The second command uses the Persist parameter of New-PSDrive to create the X: mapped network drive, which is also mapped to the \\Server01\Public network share.
PS C:\>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.
PS C:\>Get-PSDrive -Name PSDrive, X
Name Provider Root
---- -------- ----

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

The output of the Get-Member cmdlet shows that the drives have the same object type, System.Management.Automation.PSDriveInfo.
PS C:\>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()
...


However, a "net use" command, a Get-WmiObject command for the Win32_LogicalDisk class, and a Get-WmiObject command for the Win32_NetworkConnection class find only the
persistent X: drive because Windows PowerShell temporary 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 persistent, and whether the drive needs to be visible to other Windows features.
PS C:\>net use

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

PS C:\>Get-WmiObject Win32_LogicalDisk | Format-Table -Property DeviceID

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

PS C:\>Get-WmiObject Win32_NetworkConnection

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



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