{"id":51373,"date":"2010-02-07T00:01:00","date_gmt":"2010-02-07T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2010\/02\/07\/hey-scripting-guy-weekend-scripter-conversion-module-part-2\/"},"modified":"2010-02-07T00:01:00","modified_gmt":"2010-02-07T00:01:00","slug":"hey-scripting-guy-weekend-scripter-conversion-module-part-2","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/hey-scripting-guy-weekend-scripter-conversion-module-part-2\/","title":{"rendered":"Hey, Scripting Guy! Weekend Scripter: Conversion Module, Part 2"},"content":{"rendered":"

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

 <\/p>\n

Microsoft Scripting Guy Ed Wilson here. One of the cool things about writing scripts on the weekend, is the lack of distraction. Because there are few things to compete for one’s attention, there is more time to polish and more time to clean up the code. <\/p>\n<\/p>\n

For example, consider the ConversionModule.psm1 module I worked on yesterday. After I finished writing it and posted it to the SharePoint site that Craig and I share, I stretched out on the futon<\/font><\/a> in my entertainment room, put on A Midsummer Night’s Dream<\/font><\/a> by Mendelssohn, and sipped a cup of Rooibos tea<\/font><\/a>. I turned on an electric blanket and in my relaxed state thought of several things; I could do to improve the module. Ah, the beauties of weekend scripting. During the rapid pace of the normal workday, I never find time to stretch out on a futon and listen to Mendelssohn. <\/p>\n

So what is wrong with the module I wrote yesterday? Not a thing that I know of. It works. Nevertheless, there are a few things to do to improve the function. As seen in the following image some of the information that is returned by the Get-Help<\/b> cmdlet is incomplete (for example, the Description<\/b>) and some of the information (such as the data type of the input parameter) is ambiguous. <\/p>\n

\"Image<\/p>\n

The Description<\/b> is the easiest problem to fix. To fix this, you need only supply a string value for the .DESCRIPTION<\/b> tag inside the help area. It is a best practice to use a complete sentence for the description. In addition, I like to include the name of the function in the description because the Synopsis<\/b> does not generally repeat the function name. The modification is seen in the following image. <\/p>\n

\"Image<\/p>\n

\n

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

After the change has been made, save the module and use the Copy-Module.ps1 script to install the module. And after the module has been installed, import it and use the Get-Help<\/b> cmdlet to see the results. As seen in the following image, the change was successful. <\/p>\n

\"Image<\/p>\n

\n

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

We now need to add the Description<\/b> tag to each of the other functions. I use copy and paste to copy the original description from the first function and paste it in each of the other functions. After I have completed the copy-and-paste operations, I go back and edit each one in succession. <\/p>\n

The next problem that needs to be addressed is the ambiguous data type that is reported for the input parameters. As seen in the following image the feet<\/b> parameter is reported as an <Object><\/b>, which though true is less than illuminating because everything in Windows PowerShell is an object. Data types that are commonly used are integers and strings are represented as [int]<\/b> and [string]<\/b>, respectively. An integer is a whole number, and when making value conversions from Fahrenheit to Celsius, it is important to be able to use decimal places. What is that data type called? You could open Internet Explorer, navigate over to MSDN, and spend the next 30 minutes or so Binging around trying to arrive at the correct data type. Or you can use the GetType<\/b> method as seen here and quickly arrive at the System.Double<\/b> data type:<\/p>\n

PS C:> $a = 1.1111
PS C:> $a.GetType()<\/p>\n

IsPublic IsSerial Name                                     <\/span>BaseType
——– ——– —-                                     <\/span>——–
True     <\/span>True     <\/span>Double                                   <\/span>System.ValueType<\/p>\n

PS C:><\/p>\n

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

To use Double<\/b> as a type constraint, you merely place it inside a set of square brackets inside the parameter declaration. This is seen here:<\/p>\n

param(
      <\/span>[Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      <\/span>[Double]
      <\/span>$feet
) #end param<\/p>\n

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

Once again, a copy-and-paste operation is in order to fix the remaining parameter statements. The resulting Get-Help<\/b> output is seen in the following image.<\/p>\n

\"Image<\/p>\n

\n

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

In the full view of help, you can obtain more information about the input types and output types of the script. The .Inputs<\/b> and the .Outputs<\/b> tags as shown here control these values.<\/p>\n

   <\/span>.Inputs
    <\/span>[double]
   <\/span>.Outputs
    <\/span>[string]<\/p>\n

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

After the tags have been added to all the functions, and the modified module is installed and imported, you can use Get-Help<\/b> as seen in the following image.<\/p>\n

\"Image<\/p>\n

\n

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

The modified ConversionModuleV2.psm1 module is seen here. <\/p>\n

ConversionModuleV2.psm1<\/p>\n

<\/strong><\/p>\n

Function ConvertTo-Meters
{
 <\/span><#
  <\/span>.Synopsis
    <\/span>Converts feet into meters
   <\/span>.Description
    <\/span>The ConvertTo-Meters function accepts a value in feet and
    <\/span>returns a string indicating the number of meters.
   <\/span>.Example
    <\/span>ConvertTo-Meters 1
    <\/span>Converts 1 foot into meters
   <\/span>.Parameter feet
    <\/span>The number of feet to be converted
   <\/span>.Inputs
    <\/span>[double]
   <\/span>.Outputs
    <\/span>[string]
   <\/span>.Notes
    <\/span>NAME:  <\/span>ConvertTo-Meters
    <\/span>AUTHOR: Ed Wilson
    <\/span>LASTEDIT: 1\/31\/2010
    <\/span>KEYWORDS: WeekEnd Scripter, Modules, Getting Started
   <\/span>.Link
     <\/span>Http:\/\/www.ScriptingGuys.com
 <\/span>#Requires -Version 2.0
 <\/span>#>
 <\/span>[CmdletBinding()]
 <\/span>param(
      <\/span>[Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      <\/span>[Double]
      <\/span>$feet
) #end param
  <\/span>“$feet feet equals $($feet*.31) meters”
} #end ConvertTo-Meters<\/p>\n

Function ConvertTo-Feet
{
 <\/span><#
  <\/span>.Synopsis
    <\/span>Converts meters into feet
  <\/span>.Description
    <\/span>The ConvertTo-Feet function accepts a value in meters and
    <\/span>returns a string indicating the number of feet.
   <\/span>.Example
    <\/span>ConvertTo-Feet 1
    <\/span>Converts 1 meter into feet
   <\/span>.Parameter meters
    <\/span>The number of meters to be converted into feet
   <\/span>.Inputs
    <\/span>[double]
   <\/span>.Outputs
    <\/span>[string]
   <\/span>.Notes
    <\/span>NAME:  <\/span>ConvertTo-Feet
    <\/span>AUTHOR: Ed Wilson
    <\/span>LASTEDIT: 1\/31\/2010
    <\/span>KEYWORDS: WeekEnd Scripter, Modules, Getting Started
   <\/span>.Link
     <\/span>Http:\/\/www.ScriptingGuys.com
 <\/span>#Requires -Version 2.0
 <\/span>#>
 <\/span>[CmdletBinding()]
 <\/span>param(
 <\/span>     <\/span>[Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      <\/span>[Double]
      <\/span>$meters
) #end param
 <\/span>“$meters meters equals $($meters * 3.28) feet”
} #end ConvertTo-Feet<\/p>\n

Function ConvertTo-Fahrenheit
{
 <\/span><#
  <\/span>.Synopsis
    <\/span>Converts celsius into fahrenheit
  <\/span>.Description
    <\/span>The ConvertTo-Fahrenheit function accepts a value in celsius and
    <\/span>returns a string indicating the temperature in Fahrenheit.
   <\/span>.Example
    <\/span>ConvertTo-Fahrenheit 1
    <\/span>Converts 1 degree celsius into fahrenheit
   <\/span>.Parameter celsius
    <\/span>The  <\/span>temperature to be converted into fahrenheit
   <\/span>.Inputs
    <\/span>[double]
   <\/span>.Outputs
    <\/span>[string]
   <\/span>.Notes
    <\/span>NAME:  <\/span>ConvertTo-Fahrenheit
    <\/span>AUTHOR: Ed Wilson
    <\/span>LASTEDIT: 1\/31\/2010
    <\/span>KEYWORDS: WeekEnd Scripter, Modules, Getting Started
   <\/span>.Link
     <\/span>Http:\/\/www.ScriptingGuys.com
 <\/span>#Requires -Version 2.0
 <\/span>#>
 <\/span>[CmdletBinding()]
 <\/span>param(
      <\/span>[Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      <\/span>[Double]
      <\/span>$celsius
) #end param
 <\/span>“$celsius celsius equals $((1.8 * $celsius) + 32 ) fahrenheit”
} #end ConvertTo-Fahrenheit<\/p>\n

Function ConvertTo-celsius
{
 <\/span><#
  <\/span>.Synopsis
    <\/span>Converts fahrenheit into celsius
  <\/span>.Description
    <\/span>The ConvertTo-Celsius function accepts a value in fahrenheit and
    <\/span>returns a string indicating the temperature in celsius.
   <\/span>.Example
    <\/span>ConvertTo-Celsius 1
    <\/span>Converts 1 degree fahrenheit into celsius
   <\/span>.Parameter fahrenheit
    <\/span>The  <\/span>temperature to be converted
   <\/span>.Inputs
    <\/span>[double]
   <\/span>.Outputs
    <\/span>[string]
   <\/span>.Notes
    <\/span>NAME:  <\/span>ConvertTo-Celsius
    <\/span>AUTHOR: Ed Wilson
    <\/span>LASTEDIT: 1\/31\/2010
    <\/span>KEYWORDS: WeekEnd Scripter, Modules, Getting Started
   <\/span>.Link
     <\/span>Http:\/\/www.ScriptingGuys.com
 <\/span>#Requires -Version 2.0
 <\/span>#>
 <\/span>[CmdletBinding()]
 <\/span>param(
      <\/span>[Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      <\/span>[Double]
      <\/span>$fahrenheit
) #end param
 <\/span>“$fahrenheit fahrenheit equals $( (($fahrenheit – 32)\/9)*5 ) celsius”
} #end ConvertT-ocelsius<\/p>\n

Function ConvertTo-Miles
{
 <\/span><#
  <\/span>.Synopsis
    <\/span>Converts kilometers into miles
  <\/span>.Description
    <\/span>The ConvertTo-Miles function accepts a value in kilometers and
    <\/span>returns a string indicating the distance in miles.
   <\/span>.Example
    <\/span>ConvertTo-Miles
    <\/span>Converts 1 kilometer into miles
   <\/span>.Parameter kilometer
    <\/span>The distance to be converted
   <\/span>.Inputs
    <\/span>[double]
   <\/span>.Outputs
    <\/span>[string]
   <\/span>.Notes
    <\/span>NAME:  <\/span>ConvertTo-Miles
    <\/span>AUTHOR: Ed Wilson
    <\/span>LASTEDIT: 1\/31\/2010
    <\/span>KEYWORDS: WeekEnd Scripter, Modules, Getting Started
   <\/span>.Link
     <\/span>Http:\/\/www.ScriptingGuys.com
 <\/span>#Requires -Version 2.0
 <\/span>#>
 <\/span>[CmdletBinding()]
 <\/span>param(
      <\/span>[Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      <\/span>[Double]
      <\/span>$kilometer
) #end param
  <\/span>“$kilometer kilometers equals $( ($kilometer *.6211) ) miles”
} #end convertToMiles<\/p>\n

Function ConvertTo-Kilometers
{
 <\/span><#
  <\/span>.Synopsis
&nbsp\n;   <\/span>Converts miles into Kilometers
  <\/span>.Description
    <\/span>The ConvertTo-Kilometers function accepts a value in miles and
    <\/span>returns a string indicating the distance in kilometers.
   <\/span>.Example
    <\/span>ConvertTo-Kilometers 1
    <\/span>Converts 1 mile into kilometers
   <\/span>.Parameter miles
    <\/span>The distance to be converted
   <\/span>.Inputs
    <\/span>[double]
   <\/span>.Outputs
    <\/span>[string]
   <\/span>.Notes
    <\/span>NAME:  <\/span>ConvertTo-Kilometers
    <\/span>AUTHOR: Ed Wilson
    <\/span>LASTEDIT: 1\/31\/2010
    <\/span>KEYWORDS: WeekEnd Scripter, Modules, Getting Started
   <\/span>.Link
     <\/span>Http:\/\/www.ScriptingGuys.com
 <\/span>#Requires -Version 2.0
 <\/span>#>
 <\/span>[CmdletBinding()]
 <\/span>param(
      <\/span>[Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      <\/span>[Double]
      <\/span>$miles
) #end param
  <\/span>“$miles miles equals $( ($miles * 1.61) ) kilometers”
} #end convertTo-Kilometers<\/p>\n

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

If you want to know exactly what we will be covering in the coming week, follow us on Twitter<\/a> and Facebook<\/a><\/span>. If you have any questions, send e-mail to us at scripter@microsoft.com<\/font><\/a> or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.
<\/p>\n

 <\/p>\n

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

Ed Wilson and Craig Liebendorfer, Scripting Guys<\/p>\n

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

<\/p>\n

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

<\/p>\n

 <\/p>\n

<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

  Microsoft Scripting Guy Ed Wilson here. One of the cool things about writing scripts on the weekend, is the lack of distraction. Because there are few things to compete for one’s attention, there is more time to polish and more time to clean up the code. For example, consider the ConversionModule.psm1 module I worked […]<\/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":[51,52,3,4,61,45],"class_list":["post-51373","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-getting-started","tag-modules","tag-scripting-guy","tag-scripting-techniques","tag-weekend-scripter","tag-windows-powershell"],"acf":[],"blog_post_summary":"

  Microsoft Scripting Guy Ed Wilson here. One of the cool things about writing scripts on the weekend, is the lack of distraction. Because there are few things to compete for one’s attention, there is more time to polish and more time to clean up the code. For example, consider the ConversionModule.psm1 module I worked […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/51373","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=51373"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/51373\/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=51373"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=51373"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=51373"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}