{"id":13511,"date":"2011-06-26T00:01:00","date_gmt":"2011-06-26T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2011\/06\/26\/dont-write-scripts-write-powershell-functions\/"},"modified":"2011-06-26T00:01:00","modified_gmt":"2011-06-26T00:01:00","slug":"dont-write-scripts-write-powershell-functions","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/dont-write-scripts-write-powershell-functions\/","title":{"rendered":"Don't Write Scripts, Write PowerShell Functions"},"content":{"rendered":"

Summary<\/b>: There are times when piling Windows PowerShell cmdlets together becomes a bit cumbersome, so instead of writing a script, consider functions.<\/p>\n

Weekend Scripter<\/strong><\/h2>\n

Microsoft Scripting Guy, Ed Wilson, is here. There are times, when I want to do things that are a bit more complicated than piecing together cmdlets in a straightforward manner. In yesterday’s Hey! Scripting Guy blog<\/a>, I talked about not needing to write Windows PowerShell scripts. I illustrated piping cmdlets together, and working in an interactive fashion. <\/p>\n

I actually had the idea for this series while I was speaking at the TechStravaganza<\/a> in Atlanta, Georgia a month or so ago. I told them, that I was making an announcement to ITPros that it was time to quit writing scripts. Here is a picture taken of me while I was speaking on that occasion. In the picture, you can see Mark Schill, president of the Atlanta PowerShell User Group<\/a> on the left, and Mark Minassi sitting in the front row center. <\/p>\n

\"Photo<\/a><\/p>\n

In the old days, I might very well whip out a script editor and bang out a simple Windows PowerShell script. This was especially true in the Windows PowerShell 1.0 days. For example, consider a common need: to view information about disk drives on a local or remote computer. The information I normally need is things like the capacity of the drive and the amount of free space. In addition, I like to know the percentage of free space on the drive because it gives me a “feel” for how rapidly my drive space is diminishing over time. Anyway, such a script is the DiskDriveScript.ps1 Windows PowerShell script. It is shown here. <\/p>\n

\n

DiskDriveScript.ps1<\/b><\/p>\n

$drive = “c:”<\/span><\/span><\/span><\/p>\n

$computername = “.”<\/span><\/span><\/span><\/p>\n

 <\/span><\/span><\/span><\/p>\n

 <\/span><\/span>Foreach($d in $drive)<\/span><\/span><\/span><\/span><\/p>\n

 <\/span><\/span>{<\/span><\/span><\/span><\/span><\/p>\n

  <\/span><\/span>Get-WmiObject -Class win32_Volume -ComputerName $computername `<\/span><\/span><\/span><\/span><\/p>\n

      <\/span><\/span>-Filter “DriveLetter = ‘$d'” |<\/span><\/span><\/span><\/span><\/p>\n

  <\/span><\/span>Format-table -autosize -property DriveLetter, Label, <\/span><\/span><\/span><\/span><\/p>\n

  <\/span><\/span>@{Name = “ComputerName”; Expression = {$_.__Server} },<\/span><\/span><\/span><\/span><\/p>\n

  <\/span><\/span>@{Name = “Capacity(GB)”; Expression = {$_.capacity \/ 1GB} }, <\/span><\/span><\/span><\/span><\/p>\n

  <\/span><\/span>@{Name = “FreeSpace(GB)”; Expression = {$_.Freespace \/ 1GB} },<\/span><\/span><\/span><\/span><\/p>\n

  <\/span><\/span>@{Name = “PercentFree”; Expression = { ($_.FreeSpace \/ $_.Capacity)*100 } }<\/span><\/span><\/span><\/span><\/p>\n

 <\/span><\/span>} # end foreach<\/span><\/span><\/span><\/span><\/p>\n<\/blockquote>\n

The DiskDriveScript.ps1 is not a bad script. It has default values for the disk drive and the computer name. It will accept an array of drive letters, and it creates a nice custom formatted table of output. In addition, it calculates the percent of free space, and it displays the disk space in gigabytes, which is a number that is more likely to be meaningful with today’s drive sizes. <\/p>\n

However, there are a number of problems with the DiskDriveScript.ps1 script. The main problem is that it is pretty much single purpose. Although I can call the script and redirect the output to a text file, that is about as far as I can go with the script. One reason is that it outputs data in a table. When the WMI Win32_Volume<\/b> object hits the Format-Table<\/b> cmdlet it changes from a management object to a series of format-specific objects. Once a Format-Table<\/b>, Format-List<\/b>, or Format-Wide<\/b> cmdlet enters the equation, it becomes the end of the pipeline—nothing else can follow. In creating the table from within the DiskDriveScript.ps1 script, any potential code reuse is no longer possible. <\/p>\n

A more useful approach, and one that takes very little additional work, creates an advanced function instead of a single purpose script. An advanced function does require comment-based Help, but because comment-based Help is so easy to add (especially by using my Add-Help add on to the Windows PowerShell ISE<\/a>), and because it adds so much value to your function (by explaining it and illustrating potential ways to use the function), I pretty much feel that it is nearly a requirement for an advanced function. This is why I emphasized comment-based Help during the 2011 Scripting Games. <\/p>\n

The big change from the DiskDrive.ps1 script was real simple—I changed Format-Table<\/b> to Select-Object<\/b>. That is it. That simple change converts the script from a single purpose, limited-use script into a script that emits an object that is available for nearly an infinite amount of code reuse.<\/p>\n

For example, suppose I am interested in the amount of free space I have on the various drives that are connected to my computer. I can use the Get-DiskDrive<\/b> function to retrieve drive information, and then pipe the output to the Sort-Object<\/b> cmdlet. This command is shown here. <\/p>\n

\n

Get-DiskDrive -d c:,e:,g: | Sort-Object -Property percentFree<\/span><\/span><\/span><\/p>\n<\/blockquote>\n

The command and its associated output are shown in the following image.<\/p>\n

\"Image<\/a><\/p>\n

Perhaps I am interested in seeing information about how my drives are formatted. I can group the drives, based on the FileSystem<\/b> property. This command and its associated output are shown here.<\/p>\n

\n

PS C:\\Users\\ed> Get-DiskDrive -d c:,e:,g: | Group-Object -Property FileSystem -NoElement<\/span><\/span><\/span><\/p>\n

 <\/span><\/span><\/span><\/p>\n

Count Name<\/span>                     <\/span><\/span><\/span><\/span><\/p>\n

—– —-<\/span>                     <\/span><\/span><\/span><\/span><\/p>\n

    <\/span><\/span>2 NTFS<\/span>                     <\/span><\/span><\/span><\/span><\/p>\n

    <\/span><\/span>1 FAT32<\/span><\/span><\/span>                    <\/span><\/span><\/span><\/p>\n<\/blockquote>\n

If I want a bit more information, I remove the NoElement<\/i> parameter. The command and output associated with the revised command are shown here.<\/p>\n

\n

PS C:\\Users\\ed> Get-DiskDrive -d c:,e:,g: | Group-Object -Property FileSystem <\/span><\/span><\/span><\/p>\n

 <\/span><\/span><\/span><\/p>\n

Count Name                      <\/span>Group<\/span>                                                       <\/span><\/span><\/span><\/span><\/p>\n

—– —-                      <\/span>—–<\/span>                                                       <\/span><\/span><\/span><\/span><\/p>\n

    <\/span><\/span>2 NTFS                      <\/span>{@{DriveLetter=C:; Label=; FileSystem=NTFS; PageFilePrese…<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>1 FAT32                     <\/span>{@{DriveLetter=G:; Label=TESTFORMAT; FileSystem=FAT32; <\/span><\/span><\/span><\/p>\n<\/blockquote>\n

Maybe I need to know where the page file resides so I can optimize my system. Well, to do that, I add a Where-Object<\/b> as shown here.<\/p>\n

\n

PS C:\\Users\\ed> Get-DiskDrive -d c:,e:,g: | where { $_.pagefilepresent }<\/span><\/span><\/span><\/p>\n

 <\/span><\/span><\/span><\/p>\n

DriveLetter     <\/span>: C:<\/span><\/span><\/span><\/p>\n

Label           <\/span>: <\/span><\/span><\/span><\/p>\n

FileSystem      <\/span>: NTFS<\/span><\/span><\/span><\/p>\n

PageFilePresent : True<\/span><\/span><\/span><\/p>\n

ComputerName    <\/span>: NEWMRED<\/span><\/span><\/span><\/p>\n

Capacity(GB)    <\/span>: 119.142574310303<\/span><\/span><\/span><\/p>\n

FreeSpace(GB)   <\/span>: 72.1981544494629<\/span><\/span><\/span><\/p>\n

PercentFree     <\/span>: 60.5981152139833<\/span><\/span><\/span><\/p>\n<\/blockquote>\n

But, maybe I need to know the percentage of free space, the file system, and the drive letter. I add a Select-Object<\/b> command as shown here.<\/p>\n

\n

PS C:\\Users\\ed> Get-DiskDrive -d c:,e:,g: | where { $_.pagefilepresent } | select DriveLetter, Filesystem, percentFree<\/span><\/span><\/span><\/p>\n

 <\/span><\/span><\/span><\/p>\n

DriveLetter                           <\/span>FileSystem           <\/span>                                           <\/span>PercentFree<\/span><\/span><\/span><\/p>\n

———–                           <\/span>———-                                                      <\/span>———–<\/span><\/span><\/span><\/p>\n

C:                                    <\/span>NTFS                                             <\/span>          <\/span>60.5981152139833<\/span><\/span><\/span><\/p>\n<\/blockquote>\n

If I want to do so, I can even use WMI to retrieve a list of all the drives on the computer that are fixed local hard disk drives, and pipe that information to the Get-DiskDrive<\/b> function. This command is shown here (the %<\/b> character is an alias for the ForEach-Object<\/b> cmdlet). <\/p>\n

\n

gwmi win32_logicaldisk -filter “drivetype = ‘3’” | % {Get-DiskDrive -drive $_.deviceID }<\/span><\/span><\/span><\/p>\n<\/blockquote>\n

The complete Get-DiskDrive<\/b> advanced function is shown here. <\/p>\n

\n

Function Get-DiskDrive<\/span><\/span><\/span><\/p>\n

{<\/span><\/span><\/span><\/p>\n

  <\/span><\/span><#<\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Synopsis<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>This function returns capacity and freespace in gigs, and percent free<\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Description<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>This function returns capacity and freespace in gigs, and percent free. By <\/span><\/span><\/span><\/p>\n

    <\/span><\/span>default it returns the system drive (normally drive c:)<\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Example<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Get-DiskDrive<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Returns capacity and free space in gigabytes. It also returns percent free,<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>and the drive letter and drive label of the system drive on the local machine.<\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Example<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Get-DiskDrive -drive e: -computer berlin<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Returns capacity and free space in gigabytes of the e: drive. It also returns<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>percent free, and the drive letter and drive label of the system drive on the <\/span><\/span><\/span><\/p>\n

    <\/span><\/span>remote machine named berlin.<\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Example<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Get-DiskDrive -drive e: -computer berlin, munich<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Returns capacity and free space in gigabytes of the e: drive. It also returns<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>percent free, and the drive letter and drive label of the system drive on two <\/span><\/span><\/span><\/p>\n

    <\/span><\/span>remote machines named berlin and munich.<\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Example<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Get-DiskDrive -drive c:, e: -computer berlin, munich<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Returns capacity and free space in gigabytes of the C: and e: drive. It also <\/span><\/span><\/span><\/p>\n

    <\/span><\/span>returns percent free, and the drive letter and drive label of the system drive <\/span><\/span><\/span><\/p>\n

    <\/span><\/span>on two remote machines named berlin and munich.<\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Example<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>“c:”,”d:”,”f:” | % { Get-DiskDrive $_ }<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Returns information about c, d, and f drives on local computer. <\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Example<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Get-DiskDrive -d “c:”,”d:”,”f:”<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Returns information about c, d, and f drives on local computer. Same command<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>as the previous example – but easier to read. But on my computer this is a <\/span><\/span><\/span><\/p>\n

    <\/span><\/span>bit slower than the previous command (40 milliseconds).<\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Parameter drive<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>The drive letter to query.  <\/span>Defaults to system drive (normally c:)<\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Parameter computername<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>The name of the computer to query. Defaults to local machine. <\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Notes<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>NAME:  <\/span>Example-<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>AUTHOR: ed wilson, msft<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>LASTEDIT: 06\/02\/2011 16:12:08<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>KEYWORDS:<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>HSG: HSG-06-26-2011<\/span><\/span><\/span><\/p>\n

   <\/span><\/span>.Link<\/span><\/span><\/span><\/p>\n

    <\/span><\/span>Http:\/\/www.ScriptingGuys.com\/blog<\/span><\/span><\/span><\/p>\n

 <\/span><\/span>#Requires -Version 2.0<\/span><\/span><\/span><\/p>\n

 <\/span><\/span>#><\/span><\/span><\/span><\/p>\n

 <\/span><\/span>Param(<\/span><\/span><\/span><\/p>\n

  <\/span><\/span>[string[]]$drive = $env:SystemDrive,<\/span><\/span><\/span><\/p>\n

  <\/span><\/span>[string[]]$computername = $env:COMPUTERNAME<\/span><\/span><\/span><\/p>\n

 <\/span><\/span>) #end param<\/span><\/span><\/span><\/p>\n

 <\/span><\/span>Foreach($d in $drive)<\/span><\/span><\/span><\/p>\n

 <\/span><\/span>{<\/span><\/span><\/span><\/p>\n

  <\/span><\/span>Get-WmiObject -Class win32_Volume -ComputerName $computername -Filter “DriveLetter = ‘$d'” |<\/span><\/span><\/span><\/p>\n

  <\/span><\/span>Select-object DriveLetter, Label, FileSystem, PageFilePresent, <\/span><\/span><\/span><\/p>\n

  <\/span><\/span>@{Name = “ComputerName”; Expression = {$_.__Server} },<\/span><\/span><\/span><\/p>\n

  <\/span><\/span>@{Name = “Capacity(GB)”; Expression = {$_.capacity \/ 1GB} }, <\/span><\/span><\/span><\/p>\n

  <\/span><\/span>@{Name = “FreeSpace(GB)”; Expression = {$_.Freespace \/ 1GB} },<\/span><\/span><\/span><\/p>\n

  <\/span><\/span>@{Name = “PercentFree”; Expression = { ($_.FreeSpace \/ $_.Capacity)*100 } }<\/span><\/span><\/span><\/p>\n

 <\/span><\/span>} # end foreach<\/span><\/span><\/span><\/p>\n

 <\/span><\/span><\/span><\/span><\/p>\n

} #end function get-diskdrive<\/span><\/span><\/span><\/p><\/blockquote>\n

The complete Get-DiskDrive<\/b> function is uploaded to the Scripting Guys Script Repository<\/a>. This makes it easy to copy the function without worrying about getting transient HTML goop embedded in the code. <\/p>\n

I invite you to follow me on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.<\/p>\n

Ed Wilson, Microsoft Scripting Guy<\/b><\/p>\n","protected":false},"excerpt":{"rendered":"

Summary: There are times when piling Windows PowerShell cmdlets together becomes a bit cumbersome, so instead of writing a script, consider functions. Weekend Scripter Microsoft Scripting Guy, Ed Wilson, is here. There are times, when I want to do things that are a bit more complicated than piecing together cmdlets in a straightforward manner. In […]<\/p>\n","protected":false},"author":595,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[3,4,45,77],"class_list":["post-13511","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-scripting-guy","tag-scripting-techniques","tag-windows-powershell","tag-writing"],"acf":[],"blog_post_summary":"

Summary: There are times when piling Windows PowerShell cmdlets together becomes a bit cumbersome, so instead of writing a script, consider functions. Weekend Scripter Microsoft Scripting Guy, Ed Wilson, is here. There are times, when I want to do things that are a bit more complicated than piecing together cmdlets in a straightforward manner. In […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/13511","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/595"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=13511"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/13511\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=13511"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=13511"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=13511"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}