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.