20.15 Create and Map PowerShell Drives

Problem

You want to create a custom drive letter for use within PowerShell.

Solution

To create a custom drive, use the New-PSDrive cmdlet:

PS > $myDocs = [Environment]::GetFolderPath("MyDocuments")
PS > New-PSDrive -Name MyDocs -Root $myDocs -PSProvider FileSystem

Name           Used (GB)     Free (GB) Provider      Root
----           ---------     --------- --------      ----
MyDocs                         1718.98 FileSystem    G:\Lee

PS > dir MyDocs:\Cookbook

    Directory: G:\Lee\Cookbook

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
d----         7/10/2012   1:12 PM            Admin
d----         2/15/2010  10:39 AM            chapters
(...)

To create a custom drive available throughout all of Windows, use the -Persist flag:

PS > $serverDocs = "\\server\shared\documents"
PS > New-PSDrive -Name Z -Root $serverDocs -PSProvider FileSystem -Persist

Discussion

In addition to the standard drive letters you’re used to (A: through Z:), PowerShell also lets you define drives with completely custom names. Using the New-PSDrive cmdlet, you can create friendly drive names for all of your most commonly used paths.

When you use the New-PSDrive cmdlet to create a custom drive mapping, PowerShell automatically creates a new virtual drive with the name and root location that you specify. This mapping exists only for the current PowerShell session, so be sure to put it in your PowerShell profile if you want it to be available in every session.

To see the available drives in your session, type Get-PSDrive.

While extremely flexible and powerful, custom drives created this way come with some limitations. PowerShell’s core commands (Get-Item, Get-Content, etc.) all understand how to handle these virtual drives, but most of the rest of the system does not:

PS > more.com MyDocs:\blogMonitor.csv
Cannot access file G:\lee\MyDocs:\blogMonitor.csv

To resolve this issue, use the Get-Item cmdlet to convert these virtual filenames to their real filenames:

more.com (Get-Item MyDocs:\blogMonitor.csv)

While creating custom drives can provide easier access to local files, a common scenario with the New-PSDrive cmdlet is to map a drive to provide access to network resources. To do this, simply supply a UNC path to the -Root parameter of New-PSDrive.

When you supply a UNC path to the -Root parameter, PowerShell also supports a -Persist flag. When you specify -Persist, your drive becomes a persistent PowerShell drive and survives across PowerShell sessions. Unlike locally mapped drives, the items in this drive become available to all of Windows in a way that all applications can understand. For most purposes, this -Persist parameter can replace the net use command you’re most likely familiar with.

To remove a persistent mapped drive, use the Remove-PSDrive cmdlet:

Remove-PSDrive -Name Z

One additional benefit of drives created with the -Persist flag is that they support the use of alternate credentials. If you supply a -Credential parameter when mapping a network drive, PowerShell will use that credential any time it uses that drive to access files on the network location.