SAPIEN Technologies

This topic came up recently in the PowerShell forum at ScriptingAnswers.com and I thought you might find it helpful. The issue was creating a file share remotely. In the “olden days”, this would have meant using a command line tool like RMTSHARE, which is really just fine. But if you have a larger workflow, doing it natively in PowerShell may be more desirable.

Let me show you how easy it is to create a file share using Windows Management Instrumentation (WMI). I wrote a function called New-FileShare.

Function New-FileShare {

#this function returns $True is the share is successfully created

    Param([string]$computername=$env:computername,

          [string]$path=$(Throw "You must enter a complete path relative to the remote computer."),

          [string]$share=$(Throw "You must enter the name of the new share."),

          [string]$comment,

          [int]$connections

          )

    $FILE_SHARE = 0

    if (! $connections) {

        #if no connection number specifed set to $Null so

        #share will be created with maximum number of connections

        [void]$connections = $NULL

        }

    #uncomment this next line for debugging

#     Write-Host ("Creating share {0} for {1} on {2} ({3})" -f $share,$path,$computername,$comment) -fore Green

    [wmiclass]$wmishare="\\$computername\root\cimv2:win32_share"

    $return=$wmishare.Create($path,$share,$FILE_SHARE,$connections,$comment)

    Switch ($return.returnvalue) {

        0 {$rvalue = "Success"}

        2 {$rvalue = "Access Denied"}     

        8 {$rvalue = "Unknown Failure"}     

        9 {$rvalue = "Invalid Name"}     

        10 {$rvalue = "Invalid Level"}     

        21 {$rvalue = "Invalid Parameter"}     

        22 {$rvalue = "Duplicate Share"}     

        23 {$rvalue = "Redirected Path"}     

        24 {$rvalue = "Unknown Device or Directory"}

        25 {$rvalue = "Net Name Not Found"}

    }

    if ($return.returnvalue -ne 0) {

        Write-Warning ("Failed to create share {0} for {1} on {2}. Error: {3}" -f $share,$path,$computername,$rvalue) 

        return $False

    }

    else {

        return $True

    }

}

The function has the following parameters:

• –computername The name of the computer to host the share
• –path The folder path to share on the remote computer
• –share The name of the share to create. Remember you can append a $ to the name to make it a hidden share.
• –comment If you’d like to create a comment or description for the share
• –connections Specify the number of allowed concurrent connections. If you omit this parameter the share will be created to allow the maximum number of connections possible.

Here’s an example of how I might call this function:

PS C:\> New-FileShare -computername “FILE01” -path d:\Files -share “XFiles” -comment “Secret Stuff”

Let me walk you through quickly how it works. The first major task is to create an instance of the Win32_Share class on the remote computer using the [wmiclass] type adapter.

[wmiclass]$wmishare=\\$computername\root\cimv2:win32_share

Now I can call the class’ Create() method to create a new share.

$return=$wmishare.Create($path,$share,$FILE_SHARE,$connections,$comment)

The method will write a result object to the pipeline which I’ll capture as $return. The method has a few more parameters which you can learn about by reviewing the documentation for this class.

The method will write a return code that indicates if the share creation was successful or not. I use a Switch construct to decode the return value.

Switch ($return.returnvalue) {
        0 {$rvalue = “Success”}
        2 {$rvalue = “Access Denied”}    
        8 {$rvalue = “Unknown Failure”}    
        9 {$rvalue = “Invalid Name”}    
        10 {$rvalue = “Invalid Level”}    
        21 {$rvalue = “Invalid Parameter”}    
        22 {$rvalue = “Duplicate Share”}    
        23 {$rvalue = “Redirected Path”}    
        24 {$rvalue = “Unknown Device or Directory”}
        25 {$rvalue = “Net Name Not Found”}
    }

If the return value is anything other than 0, a warning message is displayed with the decoded return value.

if ($return.returnvalue -ne 0) {
        Write-Warning (“Failed to create share {0} for {1} on {2}. Error: {3}” -f $share,$path,$computername,$rvalue)
        return $False

The function will then return $False. Otherwise it will return $True.

else {
     return $True
}

This allows you to create a share and only do something else if it was created.

If (New-FileShare -computername “FILE01” -path d:\Files -share “XFiles” -comment “Secret Stuff”) {

#do something else

}

The newly created file share will use the default Share and NTFS permissions. Sure, you can modify them but I’ll leave that for you and a future post.