PowerShell How-To

How To Manage Windows File Shares with PowerShell

This automation of a commonly practiced task will end up saving you quite some time in the long run.

One task that I hate doing is clicking through Windows just to create a file share. Creating file shares is a highly common activity that many IT pros go through and is one that is ripe for automation. Creating a file share entails the the same repeatable pattern every time. Why not shave off a few minutes of your day by automating this mundane process with PowerShell? If you'd rather run a line of PowerShell than right-clicking yet another folder, this article is for you.

To get started, you'll first need to have the PowerShell cmdlets available on your system. We're going to be using the SmbShare cmdlets. These cmdlets were introduced in Windows Server 2012 R2 and Windows 8. If you have either of these operating systems or newer, you've got the cmdlets to use. If not, it's time to upgrade your operating system!

Now that we have that out of the way let's get down to it. We'll first focus on creating a new file share. Once we've done that, we'll then modify and then remove it to ensure we hit all of the important parts of managing a file share with PowerShell. For our first task, let's create a file share. To create a file share, we use the New-SmbShare cmdlet. Because you may not have a folder already created, we'll also go ahead and create a new folder as well.

New-Item -Path C:\FileShare  -ItemType Container
New-SmbShare -Path C:\FileShare -Name MyFileShare

Above, we only used two parameters to create a file share with PowerShell. In fact, only the mandatory parameters were used. At a minimum, you'll need a folder path and the name that you'd like to assign to the share. However, this is far from what's possible. If you require to create shares with different options, always check the help for that cmdlet.

PS> Get-Help New-SmbShare

NAME
New-SmbShare

SYNOPSIS
Creates an SMB share.


SYNTAX
New-SmbShare [-Name] <String> [-Path] <String> [[-ScopeName] <String>] [-CachingMode {None | Manual | Documents | Programs | BranchCache | Unknown}] [-CATimeout <UInt32>]
[-ChangeAccess <String[]>] [-CimSession <CimSession[]>] [-ConcurrentUserLimit <UInt32>] [-ContinuouslyAvailable <Boolean>] [-Description <String>] [-EncryptData <Boolean>]
[-FolderEnumerationMode {AccessBased | Unrestricted}] [-FullAccess <String[]>] [-NoAccess <String[]>] [-ReadAccess <String[]>] [-SecurityDescriptor <System.String>] [-Temporary]
[-ThrottleLimit <Int32>] [-Confirm] [-WhatIf] [<CommonParameters>]

Now that we have a file share created let's see what we can do with it. When creating the share, you can see that a lot of options are available to you but what if you don't know how you'd like to configure the file share when created? If so, we can always use the Set-SmbShare cmdlet. This cmdlet allows us to modify existing shares. Perhaps I've got an existing share, and I need to set a description on it or even maybe change the caching mode? Both of these values are easily changed using Set-SmbShare.

PS> Set-SmbShare -Name  MyFileShare -Description 'New description'

Confirm
Are you sure you want to perform this action?
Performing operation 'Modify' on Target '*,MyFileShare'.
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): a
PS> Set-SmbShare -Name MyFileShare -CachingMode Documents

Confirm
Are you sure you want to perform this action?
Performing operation 'Modify' on Target '*,MyFileShare'.
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): a
PS> Get-SmbShare -Name MyFileShare

Name        ScopeName Path         Description
----        --------- ----         -----------
MyFileShare *         C:\FileShare New description

Notice that I was prompted to confirm my choice. This is because this cmdlet's ConfirmImpact attribute is set to high. To prevent from being prompted, you can always use the -Confirm:$false parameter string. Once modified, you can then check out the properties of the file share using Get-SmbShare which, by default, does not show all of the properties but we can easily remedy that by piping the output to Select-Object and specifying all properties.

PS> Get-SmbShare -Name  MyFileShare | Select *


PresetPathAcl         : System.Security.AccessControl.DirectorySecurity
ShareState            : Online
AvailabilityType      : NonClustered
ShareType             : FileSystemDirectory
FolderEnumerationMode : Unrestricted
CachingMode           : Documents
SmbInstance           : Default
CATimeout             : 0
ConcurrentUserLimit   : 0
ContinuouslyAvailable : False
CurrentUsers          : 0
Description           : New description
EncryptData           : False
Name                  : MyFileShare
Path                  : C:\FileShare
Scoped                : False
ScopeName             : *
SecurityDescriptor    : O:SYG:SYD:(A;;0x1200a9;;;WD)
ShadowCopy            : False
Special               : False
Temporary             : False
Volume                : \\?\Volume{07efe293-0000-0000-0000-501f00000000}\
PSComputerName        :
CimClass              : ROOT/Microsoft/Windows/SMB:MSFT_SmbShare
CimInstanceProperties : {AvailabilityType, CachingMode, CATimeout, ConcurrentUserLimit...}
CimSystemProperties   : Microsoft.Management.Infrastructure.CimSystemProperties

I'm now done with this demonstration, and I'd like to clean up the file share. No problem! I can destroy the work I've done just as quickly as it was created using Remove-SmbShare. This time, however, I'd rather not be prompted. I'm sure I want to remove this share.

Remove-SmbShare -Name MyFileShare  -Confirm:$false

For a listing of all of the share cmdlets available to you use Get-Command -Name *smbshare*. You'll see that not only are the standard Get, New, Remove and Set cmdlets available, but there's also a few more as well.

About the Author

Adam Bertram is an independent consultant, technical writer, trainer and presenter. Adam specializes in consulting and evangelizing all things IT automation mainly focused around Windows PowerShell. Adam is a Microsoft Windows PowerShell MVP, 2015 powershell.org PowerShell hero and has numerous Microsoft IT pro certifications. He is a writer, trainer and presenter and authors IT pro course content for Pluralsight. He is also a regular contributor to numerous print and online publications and presents at various user groups and conferences. You can find Adam at adamtheautomator.com or on Twitter at @adbertram.

comments powered by Disqus

SharePoint Watch

Sign up for our newsletter.

I agree to this site's Privacy Policy.