Create a mapping to an SMB share. Requires PowerShell 5.0+ and Windows 10
Syntax
New-SmbMapping [[-LocalPath] String] [[-RemotePath] String] [-CimSession CimSession[]]
[-HomeFolder] [-Password String] [-Persistent Boolean] [-SaveCredentials] [-ThrottleLimit Int32]
[-UserName String] [-whatIf] [-confirm] [CommonParameters]
Key
-CimSession [CimSession[]]
Run the cmdlet in a remote session or on a remote computer.
Enter a computer name or a session object, such as the output of a New-CimSession or Get-CimSession cmdlet.
The default is the current session on the local computer.
-HomeFolder
Indicates that the connection is made to the home folder of the user.
-LocalPath [String]
A local path to which the remote path is mapped.
This is not limited to drive letters,any valid string may be used.
-Password [String]
A password to be used to connect to the SMB share.
-Persistent [Boolean]
Make this connection persistent.
-RemotePath [String]
The remote path that will be accessed from this computer.
-SaveCredentials
Save the credentials provided to use when another mapping to the same SMB server is created.
-ThrottleLimit [Int32]
The maximum number of concurrent operations that can be established to run the cmdlet.
If this parameter is omitted or a value of 0 is entered, then PowerShell will calculate an optimum throttle limit
for the cmdlet based on the number of CIM cmdlets that are running on the computer. The throttle limit applies
only to the current cmdlet, not to the session or to the computer.
-UserName [String]
The user name to use to connect to the SMB share.
-whatIf
Describe what would happen if you executed the command without
actually executing the command.
-confirm
Prompt for confirmation before executing the command.
Early versions of this cmdlet were buggy but in PowerShell 5.1+ it is considered more robust than New-PSdrive.
In Q4471218 Mapped network drives are displayed as Unavailable when you run the NET USE command.
Microsoft's recommendation is to remap them with
New-SmbMapping
This cmdlet should be run at a non-elevated session - the same privilege as Windows Explorer.
When a drive mapping is created with New-SmbMapping the new drive will not be visible to any currently running processes (including Windows Explorer) until that process is restarted (or the machine is rebooted)
The one exception to this is the PowerShell console, all PowerShell sessions on the machine will immediately get the new drive mappings.
This does mean that New-SmbMapping is not a particularly good choice for use in a user's Logon script, a VBScript drive mapping will make the drives visible immediately and also runs around 200 times faster. This faster performance is not because VBScript has some better SMB coding but simply because the entire VBScript scripting engine is a fraction of the size compared to PowerShell and so loads faster.
If you have to run PowerShell for some other purpose, such as installing some software, then mapping a drive with PowerShell will make complete sense as in that case you will be loading the PowerShell engine anyway. In many instances having the drives invisible to other non PowerShell processes may be desirable, you can map the drive, perform the operations and then disconnect with Remove-SmbMapping.
If a drive map already exists (e.g. H: ) created with NET USE / VBScript / New-SmbMapping / New-PSDrive that must be removed before a new mapping created with New-SmbMapping will succeed.
Version Available in Windows version: Support SMB 1 Windows 2000 and WIndows XP Samba 1.x
Windows 10 (1909) removes support for SMB 1.0SMB 2 Windows Server 2008 and Windows Vista SP1 Samba 3.6 SMB 2.1 Windows Server 2008 R2 and Windows 7 Samba 4.0.0 SMB 3.0 Windows Server 2012 / 2012 R2
Windows 8Samba 4.2 SMB 3.02 Windows 8.1 / Windows 2012 R2 partial see wiki SMB 3.11 Windows 10 / Windows 2016
Create an SMB mapping:
PS C:\> New-SmbMapping -LocalPath 'X:' -RemotePath '\\Server64\Germany' -persistent $True Status Local Path Remote Path ------ ---------- ----------- OK X: \\Server64\Germany
Create an SMB mapping with a try/catch to report any error:
try {
New-SmbMapping -LocalPath 'X:' -RemotePath '\\Server64\Germany' -Persistent $True
} catch {
Write-Host "There was an error mapping X: to \\Server64\Germany"
}
“Eventually everything connects - people, ideas, objects... the quality of the connections is the key to quality per se” ~ Charles Eames attr.
New-PSDrive - Create a mapped network drive (Windows 7).
Get-SmbMapping - Get Mapped SMB drives.
Get-SmbConnection - Retrieve the connections established from the SMB client to any SMB servers.
Remove-SmbMapping - Remove an SMB Mapping.
VBScript MapDrive - Map a Drive letter to a network file share.
Windows cmd command: NET USE - Map drive.