Working with Functions in Windows PowerShell

11/11/2015

Contents

Using two input parameters

To create a function that uses multiple input parameters, you use the Function keyword, specify the name of the function, use a variable for each input parameter, and then define the script block within the braces. The pattern is shown here.

Function My-Function($Input1,$Input2)
{
 #Insert Code Here
}

An example of a function that takes multiple parameters is the Get-FreeDiskSpace function, which is shown in the Get-FreeDiskSpace.ps1 script at the end of this section.

The Get-FreeDiskSpace.ps1 script begins with the Function keyword and is followed by the name of the function and the two input parameters. The input parameters are placed inside parentheses, as shown here.

Function Get-FreeDiskSpace($drive,$computer)

Inside the function’s script block, the Get-FreeDiskSpace function uses the Get-WmiObject cmdlet to query the Win32_LogicalDisk WMI class. It connects to the computer specified in the $computer parameter, and it filters out only the drive that is specified in the $drive parameter. When the function is called, each parameter is specified as -drive and -computer. In the function definition, the variables $drive and $computer are used to hold the values supplied to the parameters.

After the data from WMI is retrieved, it is stored in the $driveData variable. The data that is stored in the $driveData variable is an instance of the Win32_LogicalDisk class. This variable contains a complete instance of the class. The members of this class are shown in Table 6-1.

TABLE 6-1 Members of the Win32_LogicalDisk class

Name	Member type	Definition
Chkdsk	Method	System.Management.ManagementBaseObject Chkdsk(System.Boolean FixErrors, System.Boolean VigorousIndexCheck, System.Boolean SkipFolderCycle, System.Boolean ForceDismount, System.Boolean RecoverBadSectors, System.Boolean OkToRunAtBootUp)
Reset	Method	System.Management.ManagementBaseObject Reset()
SetPowerState	Method	System.Management.ManagementBaseObject SetPowerState(System.UInt16 PowerState, System.String Time)
Access	Property	System.UInt16 Access {get;set;}
Availability	Property	System.UInt16 Availability {get;set;}
BlockSize	Property	System.UInt64 BlockSize {get;set;}
Caption	Property	System.String Caption {get;set;}
Compressed	Property	System.Boolean Compressed {get;set;}
ConfigManagerErrorCode	Property	System.UInt32 ConfigManagerErrorCode {get;set;}
ConfigManagerUserConfig	Property	System.Boolean ConfigManagerUserConfig {get;set;}
CreationClassName	Property	System.String CreationClassName {get;set;}
Description	Property	System.String Description {get;set;}
DeviceID	Property	System.String DeviceID {get;set;}
DriveType	Property	System.UInt32 DriveType {get;set;}
ErrorCleared	Property	System.Boolean ErrorCleared {get;set;}
ErrorDescription	Property	System.String ErrorDescription {get;set;}
ErrorMethodology	Property	System.String ErrorMethodology {get;set;}
FileSystem	Property	System.String FileSystem {get;set;}
FreeSpace	Property	System.UInt64 FreeSpace {get;set;}
InstallDate	Property	System.String InstallDate {get;set;}
LastErrorCode	Property	System.UInt32 LastErrorCode {get;set;}
MaximumComponentLength	Property	System.UInt32 MaximumComponentLength {get;set;}
MediaType	Property	System.UInt32 MediaType {get;set;}
Name	Property	System.String Name {get;set;}
NumberOfBlocks	Property	System.UInt64 NumberOfBlocks {get;set;}
PNPDeviceID	Property	System.String PNPDeviceID {get;set;}
PowerManagementCapabilities	Property	System.UInt16[] PowerManagementCapabilities {get;set;}
PowerManagementSupported	Property	System.Boolean PowerManagementSupported {get;set;}
ProviderName	Property	System.String ProviderName {get;set;}
Purpose	Property	System.String Purpose {get;set;}
QuotasDisabled	Property	System.Boolean QuotasDisabled {get;set;}
QuotasIncomplete	Property	System.Boolean QuotasIncomplete {get;set;}
QuotasRebuilding	Property	System.Boolean QuotasRebuilding {get;set;}
Size	Property	System.UInt64 Size {get;set;}
Status	Property	System.String Status {get;set;}
StatusInfo	Property	System.UInt16 StatusInfo {get;set;}
SupportsDiskQuotas	Property	System.Boolean SupportsDiskQuotas {get;set;}
SupportsFileBasedCompression	Property	System.Boolean SupportsFileBasedCompression {get;set;}
SystemCreationClassName	Property	System.String SystemCreationClassName {get;set;}
SystemName	Property	System.String SystemName {get;set;}
VolumeDirty	Property	System.Boolean VolumeDirty {get;set;}
VolumeName	Property	System.String VolumeName {get;set;}
VolumeSerialNumber	Property	System.String VolumeSerialNumber {get;set;}
__CLASS	Property	System.String __CLASS {get;set;}
__DERIVATION	Property	System.String[] __DERIVATION {get;set;}
__DYNASTY	Property	System.String __DYNASTY {get;set;}
__GENUS	Property	System.Int32 __GENUS {get;set;}
__NAMESPACE	Property	System.String __NAMESPACE {get;set;}
__PATH	Property	System.String __PATH {get;set;}
__PROPERTY_COUNT	Property	System.Int32 __PROPERTY_COUNT {get;set;}
__RELPATH	Property	System.String __RELPATH {get;set;}
__SERVER	Property	System.String __SERVER {get;set;}
__SUPERCLASS	Property	System.String __SUPERCLASS {get;set;}
PSStatus	Property set	PSStatus {Status, Availability, DeviceID, StatusInfo}
ConvertFromDateTime	Script method	System.Object ConvertFromDateTime();
ConvertToDateTime	Script method	System.Object ConvertToDateTime();

When you have the data stored in the $driveData variable, you will want to print some information to the user of the script. The first thing to do is print the name of the computer and the name of the drive. To do this, you can place the variables inside double quotation marks. Double quotation marks denote expanding strings, and variables placed inside double quotation marks emit their value, not their name. This is shown here.

"$computer free disk space on drive $drive"

The next thing you will want to do is format the data that is returned. To do this, use the Microsoft .NET Framework format strings to specify two decimal places. You will need to use a subexpression to prevent the unraveling of the WMI object inside the expanding-string double quotation marks. The subexpression uses the dollar sign and a pair of parentheses to force the evaluation of the expression before returning the data to the string. This is shown here.

Get-FreeDiskSpace.ps1

Function Get-FreeDiskSpace($drive,$computer)
{
 $driveData = Get-WmiObject -class win32_LogicalDisk `
 -computername $computer -filter "Name = '$drive'"
"
 $computer free disk space on drive $drive
    $("{0:n2}" -f ($driveData.FreeSpace/1MB)) MegaBytes
"
}

Get-FreeDiskSpace -drive "C:" -computer "C10"

Obtaining specific WMI data

Though storing the complete instance of the object in the $driveData variable is a bit inefficient due to the amount of data it contains, in reality the class is rather small, and the ease of using the Get-WmiObject cmdlet is usually worth the wasteful methodology. If performance is a primary consideration, the use of the [wmi] type accelerator would be a better solution. To obtain the free disk space by using this method, you would use the following syntax.

([wmi]"Win32_logicalDisk.DeviceID='c:'").FreeSpace

To put the preceding command into a usable function, you would need to substitute the hard-coded drive letter for a variable. In addition, you would want to modify the class constructor to receive a path to a remote computer. The newly created function is contained in the Get-DiskSpace.ps1 script, shown here.

Get-DiskSpace.ps1

Function Get-DiskSpace($drive,$computer)
{
 ([wmi]"\\$computer\root\cimv2:Win32_logicalDisk.DeviceID='$drive'").FreeSpace
}
Get-DiskSpace -drive "C:" -computer "Office"

After you have made the preceding changes, the code only returns the value of the FreeSpace property from the specific drive. If you were to send the output to Get-Member, you would find that you have an integer. This technique is more efficient than storing an entire instance of the Win32_LogicalDisk class and then selecting a single value.

Save to your account