Summary: Microsoft Scripting Guy, Ed Wilson, talks about a Windows PowerShell function to determine miles remaining to meet challenge.

Microsoft Scripting Guy, Ed Wilson, is here. If you are friends with me on Facebook, you know that in October I accepted a challenge to run a hundred miles before January 31, 2015. I was doing really well until I was knocked out of the action by surgery. The other day the doctor gave me a clearance to begin exercising again. Now, I need to know how many miles I need to do, per day, to complete the 100-mile challenge.

When I was on the treadmill this morning, I decided that this was the perfect challenge for Windows PowerShell—determining how many miles to run a day (well, not actually running the miles…Jeffery Hicks aside, Windows PowerShell looks pretty strange on a pair of running shoes).

The Get-Miles Windows PowerShell function is really simple. I did not even add any Help to it because I will be using it for the next month or so, and then it will have outlived its usefulness.

So how does it work?

The first thing I do is use the Function keyword to tell Windows PowerShell I want to create a function. Next, I assign a name. I like to use Verb-Noun naming conventions when creating function names because it promotes function discoverability.

I create a single input parameter. This input parameter is my total mileage that I have run to date. Obviously, this will change on a daily basis (or at least I hope it will change on a daily basis). When I run, I always run complete miles. So it will be something like 1, 2, 3, or 4 miles. I do not do partial miles, so I cast my input type as an integer. Here is my script so far:

Function Get-Miles {

    Param ([int]$miles)

Everything else in the function is automatic because I know the following information:

• The end date. I have to complete the challenge by January 31, 2015. This is a static value that will not change.
• The distance. I have to complete 100 miles. This is also a static value that will not change.
• The current date. Every time I run the function, I want to know how many miles I will need to do per day, to reach my goal within the allotted time. I am always basing my answer on the current date.

I create two variables to hold my static values. I could create constants instead of variables for this—but hey, there is no real reason for doing this. I am not going to change the values, so they will be constant enough. Here are the value assignments:

$end = "1/31/2015"

$distance = 100

Now I create a TimeSpan object that will represent the amount of time between now and January 31, 2015. I am only interested in the number of days—and Days is one of the properties of a TimeSpan object. I store the number of days in a variable that I call $days. Here is the command:

$days = (New-TimeSpan -Start (get-date) -End ([datetime]$end)).Days

I now need to do a little bit of math work. I want to calculate the number of miles per day that I need to run to meet my goal of 100 miles by the end of January. To do this, I use my static distance value of 100 (stored in the $distance variable), and I subtract the number of miles I have run to date.

Because I will know this value when I call the function, I use the variable that holds my parameter here. Then I divide by the number of days remaining (which I obtained from my TimeSpan object). Here is the command:

$milesPerDay = ($distance – $miles)/ $days

The last thing to do is format my output. Because I am not interested in a large number of digits of output (in fact, the treadmill at the gym only displays tenths of miles), the answer I need is mileage that is precise to a tenth of a mile. If I go over the requisite amount each day (remember I always run to a complete mile), I will be assured of meeting my goal. Here is the line of code that formats the output:

"Run {0:N1} miles per day" -f $milesPerDay}

The complete function is shown here:

Function Get-Miles {

    Param ([int]$miles)

    $end = "1/31/2015"

    $distance = 100

    $days = (New-TimeSpan -Start (get-date) -End ([datetime]$end)).Days

    $milesPerDay = ($distance – $miles)/ $days

    "Run {0:N1} miles per day" -f $milesPerDay}

I could add it to my Windows PowerShell profile—but I will be only using this function every few days for the next few weeks, so it is not worth the trouble. I will, however, copy it to my scratch folder so it will be easy-to-use.

I could call it from the command line in the Windows PowerShell console. But for me, it is easier to simply open it up in the Windows PowerShell ISE. I run the function by pressing the big green triangle, and then I call the function from the immediate pane. The following image provides an example of using the function:

That is all there is to using Windows PowerShell to determine miles left to run. Join me tomorrow when I will talk about more cool Windows PowerShell stuff.

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

Ed Wilson, Microsoft Scripting Guy