Home > Sample chapters

Working with Functions in Windows PowerShell

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"