Script Wars: The Farce Awakens (part IV)


Summary: A quick recap shall we? Newly graduated from IT training and future guru in the world of Windows PowerShell, Rey Skyworker has been hired on by her mentor, Ben Kerberosie. Already, she has helped peers from her team improve their PowerShell code to do some basic error trapping and cleanup of the data upon entry.

Not bad for somebody on their first day, eh?

Oh, almost forgot, her shoelaces have been chosen as lunch by a new Beta cleaning robot with more suction than common sense.

Shall we continue? Let's!

--------------------------

Tin has been left back to tend to the help desk, while Ben continues down the hall to introduce Rey to the shipping department.

"They nickname themselves 'Falcon.' They have a very efficient shipping system, supplemented with some Windows PowerShell scripts. I'd like you to see if there is anything that can be done to improve it."

Rey nodded, "But I need to ask, why do they nickname themselves 'Falcon?'"

Ben smiled. "I'll let them explain that one to you."

Coming around the corner, they ran into two fellows. One walked in with a swagger, the other with such a heavy beard he looked like the character from the old TV show, Grizzly Adams.

"Rey, I'd like you to meet Don Yolo and Lou Hackah. Our team from shipping with a flair for some PowerShell!"

"Hey!" Don offered up his hand to shake, while all you heard from Lou was a loud growl.

"Don't worry about Lou, he tends to grunt and growl an awful lot lately. He threw his back out the other week trying to lift a pallet of Tilley hats on a bet. 'Just how heavy could they be?' he asked me. 'They're just hats!' he kept saying."

Lou just looked over at Don, suggesting he not do the "I told you so" look again. The motion caused him to roar out with pain.

"Strange too, Don seems to understand everything Lou says when he yowls in pain or grunts. They have a very special relationship you see."

Rey smiled. "Don, I have a silly question. Why do you nickname yourselves the 'Falcon' group?"

"Oh that!" Don smiled. "We're the fastest shipping division in the area. We usually ship 12 parcels in the time is takes to do a Kettle Run!"

"Kettle Run?" Rey looked over quizzically.

"Yes, you know. The time it takes to boil water in a kettle? For tea?"

Ben looked over. "I told you it was worth asking," he winked.

"So Don, they tell me you've some really cool PowerShell scripts running here!"

The scruffy looking fellow reached past a fenced-in collection of nerf balls on his desk to open up the console. "I don't know about cool, but we have a simple script we use constantly. It keeps us and the customers aware of the shipping status."

Don opened up the script in his PowerShell ISE.

$r=Invoke-RestMethod -Uri 'https://shipping.contoso.com/api.svc' -Method Get -OutFile m.pdf
If ($r.result -eq 'SUCCESS') { Send-MailMessage -Attachments m.pdf -Bcc ship@contoso.local -From shippingsystem@contoso.local -Body "Confirmation of Shipment for Customer $($r.Name) - Shipped $($r.date)" -To "$($r.email)" -Subject 'Shipping confirmation' -SMTPServer 'smtp.contoso.com' } else { Write-Host "Tr Err $($.errorcode)" }

Rey's eyes popped open. "What does it do?"

"Well, it is a pretty simple script. It connects to our internal REST API, written by our development team for the shipping system. It pulls down the status of all shipments and when they are complete, it emails us here at Falcon and the customer with the status."

Rey and Ben both looked at the code. They understood what was being said, but the code was hard to understand. Ben looked over at Don. "Do we have some documentation on this? It sounds like a useful business tool."

Don shrugged his shoulders. "Really haven't had the time." Lou roared in pain as he laughed.

"We could," Rey suggested, "make some minor changes to the code. By spacing it out, adding more variables and comments…. It could be self-documenting."

Ben looked over. "That could work. Don, if you have a few minutes to work with Rey, this could allow you to take that long desired vacation you and Lou were due for. With documentation, we could even offload this as a standard script for Infrastructure to manage."

"Less on my plate?" Don jumped up. "Let's do it!"

The first thing Rey did was back up the original script. She then broke apart the script with some spacing.  "I find separating the lines visually and using tabs to indent blocks makes things easier to view when I have to troubleshoot."

$r=Invoke-RestMethod -Uri 'https://shipping.contoso.com/api.svc' -Method Get -OutFile m.pdf

If ($r.result -eq 'SUCCESS')

{

Send-MailMessage -Attachments m.pdf -Bcc ship@contoso.local -From shippingsystem@contoso.local -Body "Confirmation of Shipment for Customer $($r.Name) - Shipped $($r.date)" -To "$($r.email)" -Subject 'Shipping confirmation' -SMTPServer 'smtp.contoso.com'

}

else

{

Write-Host "Tr Err $($.errorcode)"

}

"We can also use the backtick character to split the one long line apart into more readable chunks. You just need to make sure there is a space preceding its use."

$r=Invoke-RestMethod -Uri 'https://shipping.contoso.com/api.svc' -Method Get -OutFile m.pdf

If ($r.result -eq 'SUCCESS')

{

Send-MailMessage -Attachments m.pdf -Bcc ship@contoso.local `

-From shippingsystem@contoso.local `

-Body "Confirmation of Shipment for Customer $($r.Name) - Shipped $($r.date)" `

-To "$($r.email)" -Subject 'Shipping confirmation' `

-SMTPServer 'smtp.contoso.com'

}

else

{

Write-Host "Tr Err $($.errorcode)"

}

Don smiled. "Hey that's pretty cool. I didn't know about that backtick trick. I mean the script works, but it does look easier to read and understand already."

"We can also use very descriptive variables in PowerShell," Rey offered up. "This makes it almost like you're reading a document that has the script explain itself to others editing it or supporting it. I'm guessing $r is the Result of the REST Method?"

Don nodded as Rey made a slight update to the code.

$ResultOfShippingQuery=Invoke-RestMethod -Uri 'https://shipping.contoso.com/api.svc' -Method Get -OutFile m.pdf

If ($ResultOfShippingQuery.result -eq 'SUCCESS')

{

Send-MailMessage -Attachments m.pdf -Bcc ship@contoso.local `

-From shippingsystem@contoso.local `

-Body "Confirmation of Shipment for Customer $($ResultOfShippingQuery.Name) - Shipped $($ResultOfShippingQuery.date)" `

-To "$($ResultOfShippingQuery.email)" -Subject 'Shipping confirmation' `

-SMTPServer 'smtp.contoso.com'

}

else

{

Write-Host "Tr Err $($ResultOfShippingQuery.errorcode)"

}

"What I like to do as well," Rey noted, "is use a variable for anything that is being passed as a parameter to a cmdlet. It allows to me to put all the information somebody might need to change, such as an email address, outside of the code. It also makes that part easier to view and edit for a non-scripter or level 1 support."

She updated the script to move all content being passed as parameters as new variables, near the top of Don's script.

$ShippingManifest='m.pdf'

$ShippingApplicationRESTAPI='https://shipping.contoso.com/api.svc'

$ShippingApplicationMethod='GET'

$ResultOfShippingQuery=Invoke-RestMethod -Uri $ShippingApplicationRESTAPI -Method $ShippingApplicationMethod -OutFile $ShippingManifest

$ShippingStatus=$ResultOfShippingQuery.result

If ($ShippingStatus -eq 'SUCCESS')

{

$From='shippingsystem@contoso.local'

$Bcc='ship@contoso.local'

$SMTPServer='smtp.contoso.com'

$To=$ResultOfShippingQuery.email

$ShipmentDate=$ResultofShippingQuery.date

$CustomerName=$ResultOfShippingQuery.Name

$Subject='Shipping Confirmation'

$Body="Confirmation of Shipment for Customer $CustomerName - Shipped $ShipmentDate"

Send-MailMessage -Attachments $ShippingManifest -Bcc $Bcc -From $From -Body $Subject -To $To `

-Subject $Subject -SmtpServer $SMTPServer

}

else

{

Write-Host "Tr Err $ShippingStatus"

}

Don glanced over. "I'm blown away! You're right. It does almost read like a document."

"You can also add lines with a number sign as comments, to further explain parts of the code," Ben noted.

He entered in a simple example for Don and Lou to see.

# Shipping Rest API connection documentation

# stored on \\Contoso-fs\Docs\Dev\ShippingAPI.docx

# For explanation of use and updated documentation please refer here.

$ShippingManifest='m.pdf'

$ShippingApplicationRESTAPI='https://shipping.contoso.com/api.svc'

$ShippingApplicationMethod='GET'

"Wow! So it looks like there are some standard ways things should be written in Windows PowerShell. Is there somewhere online I can view this?"

"I'll email some great links to help with how you should be writing PowerShell code." Rey emailed the following links to Don.

Style guidelines for the creation of DSC resources:

https://github.com/PowerShell/DscResources/blob/master/BestPractices.md

https://github.com/PowerShell/DscResources/blob/master/StyleGuidelines.md

An excellent offering from the community on Style guidelines for PowerShell:

https://github.com/PoshCode/PowerShellPracticeAndStyle

Rey waved a quick goodbye to Don and Lou. They were about to head to the door, when a large, ominous presence stood blocking their way.

"WHO DO I SPEAK TO ABOUT CLEAR TEXT PASSWORDS in POWERSHELL!?!"

Who is this mysterious entity? What are its intentions? Will TB-7 attack its shoelaces instead?

Find out these and other bizarrely enticing answers in the next exciting episode of "Script Wars."

Sean Kearney, Premier Field Engineer

Enterprise Services Delivery, Secure Infrastructure

Comments (0)

Skip to main content