{"id":51513,"date":"2010-01-21T00:01:00","date_gmt":"2010-01-21T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2010\/01\/21\/hey-scripting-guy-can-you-give-all-the-steps-for-creating-installing-and-using-windows-powershell-modules\/"},"modified":"2010-01-21T00:01:00","modified_gmt":"2010-01-21T00:01:00","slug":"hey-scripting-guy-can-you-give-all-the-steps-for-creating-installing-and-using-windows-powershell-modules","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/hey-scripting-guy-can-you-give-all-the-steps-for-creating-installing-and-using-windows-powershell-modules\/","title":{"rendered":"Hey, Scripting Guy! Can You Give All the Steps for Creating, Installing, and Using Windows PowerShell Modules?"},"content":{"rendered":"

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

 \n\"Hey,<\/font><\/p>\n

Hey, Scripting Guy! I am still a bit confused about how modules work. Could you give a beginning-to-end scenario and go through the steps of creating a module, installing the module, and then using the module?<\/p>\n

— SL<\/p>\n

\n

 <\/p>\n

\"Hey,Hello, SL. <\/p>\n

Microsoft Scripting Guy Ed Wilson here. I am sipping a cup of organic tea that is grown in Hawaii. It is lightly infused with a strawberry flavor. I do not normally care for infused flavored teas. I prefer natural tea and natural flavors. However, this tea has a nice bouquet with a hint of fruit on the palate with a subtle finish. It goes well with the oatmeal, apple, and walnut cookies the Scripting Wife made. She uses extra apples for a natural sweetness in her own recipe that does not call for any flour or sugar. Instead of flour, she used crushed walnuts. How about that? A totally healthy cookie. I enjoy drinking Hawaii tea, particular when it is cold outside. I close my eyes, and I feel a mountain breeze. I can hear the roar of the waterfall. I am on Kauai with my laptop, writing a Windows PowerShell script and enjoying the Wailua Falls<\/font><\/a>:<\/p>\n

\"Image<\/p>\n

 <\/p>\n

SL, let us start at the beginning. The first thing you will probably want to do is create a module. You can create a module in the Windows PowerShell ISE. One of the first things to do is to locate a couple of functions you wish to store in the module; you can copy them directly into the Windows PowerShell ISE, as seen in this image.<\/p>\n

\"Image<\/p>\n

 <\/p>\n

After you have copied your functions into the new module, save the module with the .PSM1 extension. The basicFunctions.psm1 module is seen here. <\/p>\n

BasicFunctions.psm1<\/p>\n

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

Function Get-OptimalSize
{
 <\/span><#
  <\/span>.Synopsis
    <\/span>Converts Bytes into the appropriate unit of measure.
   <\/span>.Description
    <\/span>The Get-OptimalSize function converts bytes into the appropriate unit of
    <\/span>measure. It returns a string representation of the number.
   <\/span>.Example
    <\/span>Get-OptimalSize 1025
    <\/span>Converts 1025 bytes to 1.00 KiloBytes
    <\/span>.Example
    <\/span>Get-OptimalSize -sizeInBytes 10099999
    <\/span>Converts 10099999 bytes to 9.63 MegaBytes
   <\/span>.Parameter SizeInBytes
    <\/span>The size in bytes to be converted
   <\/span>.Inputs
    <\/span>[int64]
   <\/span>.OutPuts
    <\/span>[string]
   <\/span>.Notes
    <\/span>NAME:  <\/span>Get-OptimalSize
    <\/span>AUTHOR: Ed Wilson
    <\/span>LASTEDIT: 1\/4\/2010
    <\/span>KEYWORDS:
   <\/span>.Link
     <\/span>Http:\/\/www.ScriptingGuys.com
 <\/span>#Requires -Version 2.0
 <\/span>#>
[CmdletBinding()]
param(
      <\/span>[Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      <\/span>[int64]
      <\/span>$sizeInBytes
) #end param
 <\/span>Switch ($sizeInBytes)
  <\/span>{
   <\/span>{$sizeInBytes -ge 1TB} {“{0:n2}” -f  <\/span>($sizeInBytes\/1TB) + ” TeraBytes”;break}
   <\/span>{$sizeInBytes -ge 1GB} {“{0:n2}” -f  <\/span>($sizeInBytes\/1GB) + ” GigaBytes”;break}
   <\/span>{$sizeInBytes -ge 1MB} {“{0:n2}” -f  <\/span>($sizeInBytes\/1MB) + ” MegaBytes”;break}
   <\/span>{$sizeInBytes -ge 1KB} {“{0:n2}” -f  <\/span>($sizeInBytes\/1KB) + ” KiloBytes”;break}
   <\/span>Default { “{0:n2}” -f $sizeInBytes + ” Bytes” }
  <\/span>} #end switch
  <\/span>$sizeInBytes = $null
} #end Function Get-OptimalSize <\/p>\n

Function Get-ComputerInfo
{
 <\/span><#
  <\/span>.Synopsis
    <\/span>Retrieves basic information about a computer.
   <\/span>.Description
    <\/span>The Get-ComputerInfo cmdlet retrieves basic information such as
    <\/span>computer name, domain name, and currently logged on user from
    <\/span>a local or remote computer.
   <\/span>.Example
    <\/span>Get-ComputerInfo
    <\/span>Returns comptuer name, domain name and currently logged on user
    <\/span>from local computer.
    <\/span>.Example
    <\/span>Get-ComputerInfo -computer berlin
    <\/span>Returns comptuer name, domain name and currently logged on user
    <\/span>from remote computer named berlin.
   <\/span>.Parameter Computer
    <\/span>Name of remote computer to retrieve information from
   <\/span>.Inputs
    <\/span>[string]
   <\/span>.OutPuts
    <\/span>[object]
   <\/span>.Notes
    <\/span>NAME:  <\/span>Get-ComputerInfo
    <\/span>AUTHOR: Ed Wilson
    <\/span>LASTEDIT: 1\/11\/2010
    <\/span>KEYWORDS:
   <\/span>.Link
     <\/span>Http:\/\/www.ScriptingGuys.com
 <\/span>#Requires -Version 2.0
 <\/span>#>
 <\/span>Param([string]$computer=”localhost”)
 <\/span>$wmi = Get-WmiObject -Class win32_computersystem -ComputerName $computer
 <\/span>$pcinfo = New-Object -TypeName system.object
 <\/span>$pcInfo | Add-Member -MemberType noteproperty -Name host -Value $($wmi.DNSHostname)
 <\/span>$pcInfo | Add-Member -MemberType noteproperty -Name domain -Value $($wmi.Domain)
 <\/span>$pcInfo | Add-Member -MemberType noteproperty -Name user -Value $($wmi.Username)
 <\/span>$pcInfo
}<\/p>\n

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

You can control what is exported from the module by creating a manifest. If you place related functions that you will more than likely want to use together, you can avoid creating a manifest. In the BasicFunctions.psm1 module, there are two functions, one of which was created during Microsoft Visio Week<\/a>.<\/p>\n

The Get-ComputerInfo<\/b> function was written for today’s Hey, Scripting Guy! post and is used to return a custom object that contains information about the user, computer name, and computer domain. After you have created and saved the module, you will need to install the module. You can do this manually by navigating to the module directory, creating a folder for the module, and placing a copy of the module in the folder. I prefer to use the Copy-Modules.ps1 script that was discussed on Tuesday<\/a>. <\/p>\n

After the module has been copied to its own directory, you can use the Import-Module<\/b> cmdlet to import it into the current Windows PowerShell session. If you are not sure of the name of the module, you can use the Get-Module<\/b> cmdlet with the –ListAvailable<\/b> switch, as seen here:<\/p>\n

PS C:> Get-Module -ListAvailable<\/p>\n

ModuleType Name           <\/span>           <\/span>ExportedCommands
———- —-                      <\/span>—————-
Script     <\/span>BasicFunctions            <\/span>{}
Script     <\/span>DotNet                    <\/span>{}
Manifest   <\/span>FileSystem                <\/span>{}
Manifest   <\/span>IsePack                   <\/span>{}
Manifest   <\/span>PowerShellPack            <\/span>{}
Manifest   <\/span>PSCodeGen                 <\/span>{}
Manifest   <\/span>PSImageTools              <\/span>{}
Manifest   <\/span>PSRSS                     <\/span>{}
Manifest   <\/span>PSSystemTools             <\/span>{}
Manifest   <\/span>PSUserTools               <\/span>{}
Manifest   <\/span>TaskScheduler      <\/span>       <\/span>{}
Manifest   <\/span>WPK                       <\/span>{}
Manifest   <\/span>ActiveDirectory           <\/span>{}
Manifest   <\/span>AppLocker                 <\/span>{}
Manifest   <\/span>BitsTransfer              <\/span>{}
Manifest   <\/span>FailoverClusters          <\/span>{}
Manifest   <\/span>GroupPolicy               <\/span>{}
Manifest   <\/span>NetworkLoadBalancingCl… {}
Manifest   <\/span>PSDiagnostics             <\/span>{}
Manifest   <\/span>TroubleshootingPack       <\/span>{}<\/p>\n

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

After you have imported the module, you can use the Get-Command<\/b> cmdlet with the –module<\/b> parameter to see which commands are exported by the module. This is illustrated in the following image.<\/p>\n

\"Image<\/p>\n

 <\/p>\n

After you have added the functions from the module, you can use them directly from the Windows PowerShell prompt. Using the Get-ComputerInfo<\/b> function is illustrated here:<\/p>\n

PS C:> Get-ComputerInfo<\/p>\n

host                                    <\/span>domain                                  <\/span>user
—-                                    <\/span>——          <\/span>                        <\/span>—-
mred1                                   <\/span>NWTraders.Com                           <\/span>NWTRADERSed<\/p>\n

PS C:> (Get-ComputerInfo).user
NWTRADERSed
PS C:> (Get-ComputerInfo).host
mred1
PS C:> Get-ComputerInfo -computer win7-pc | Format-Table -AutoSize<\/p>\n

host    <\/span>domain        <\/span>user
—-    <\/span>——        <\/span>—-
win7-PC NWTraders.Com NWTRADERSAdministrator<\/p>\n

PS C:><\/p>\n

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

Because the help tags were used when creating the functions, you can use the Get-Help<\/b> cmdlet to obtain information about using the function. In this manner, the function that was created in the module behaves exactly like a regular Windows PowerShell cmdlet. This includes tab expansion. <\/p>\n

PS C:> Get-Help Get-ComputerInfo<\/p>\n

NAME
    <\/span>Get-ComputerInfo<\/p>\n

SYNOPSIS
    <\/span>Retrieves basic information about a computer.<\/p>\n

SYNTAX
    <\/span>Get-ComputerInfo [[-computer] <String>] [<CommonParameters>]<\/p>\n

DESCRIPTION
    <\/span>The Get-ComputerInfo cmdlet retrieves basic information such as
    <\/span>computer name, domain name, and currently logged on user from
    <\/span>a local or remote computer.<\/p>\n

RELATED LINKS
    <\/span>Http:\/\/www.ScriptingGuys.com
    <\/span>#Requires -Version 2.0<\/p>\n

REMARKS
    <\/span>To see the examples, type: “get-help Get-ComputerInfo -examples”.
    <\/span>For more information, type: “get-help Get-ComputerInfo -detailed”.
    <\/span>For technical information, type: “get-help Get-ComputerInfo -full”.<\/p>\n

PS C:> Get-Help Get-ComputerInfo -Examples<\/p>\n

NAME
    <\/span>Get-ComputerInfo<\/p>\n

SYNOPSIS
    <\/span>Retrieves basic information about a computer.<\/p>\n

    <\/span>————————– EXAMPLE 1 ————————–<\/p>\n

    <\/span>C:PS>Get-ComputerInfo<\/p>\n

    <\/span>Returns comptuer name, domain name and currently logged on user
    <\/span>from local computer.<\/p>\n

    <\/span>————————– EXAMPLE 2 ————————–<\/p>\n

    <\/span>C:PS>Get-ComputerInfo -computer berlin<\/p>\n

    <\/span>Returns comptuer name, domain name and currently logged on user
    <\/span>from remote computer named berlin.<\/p>\n

PS C:><\/p>\n

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

The Get-OptimalSize<\/b> function can even receive input from the pipeline, as shown here:<\/p>\n

PS C:> (get-WmiObject win32_volume -Filter “driveletter = ‘c:'”).freespace<\/p>\n

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

26513960960<\/p>\n

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

PS C:> (get-WmiObject win32_volume -Filter “driveletter = ‘c:'”).freespace | Get-OptimalSize<\/p>\n

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

24.69 GigaBytes<\/p>\n

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

PS C:><\/p>\n

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

Pretty cool, huh? Okay, SL, here are the steps:<\/p>\n

1.     <\/span><\/span><\/span>Place functions into a module, and save it with a .psm1 extension.<\/p>\n

2.     <\/span><\/span><\/span>Copy the module to the modules directory. Use the Copy-Modules.ps1 script to do this.<\/p>\n

3.     <\/span><\/span><\/span>Obtain a list of available modules by using the Get-Modules<\/b> cmdlet with the –listavailable<\/b> switched parameter.<\/p>\n

4.     <\/span><\/span><\/span>Import modules into your current Windows PowerShell session by using the Import-Module<\/b> cmdlet.<\/p>\n

5.     <\/span><\/span><\/span>See which commands are available from the module by using the Get-Command<\/b> cmdlet with the –module<\/b> parameter.<\/p>\n

6.     <\/span><\/span><\/span>Use the Get-Help<\/b> cmdlet to obtain information about the exported functions.<\/p>\n

7.     <\/span><\/span><\/span>Use the functions like you would use any other cmdlet. <\/p>\n

 <\/p>\n

SL, that is all there is to installing and using a Windows PowerShell module. And this concludes Windows PowerShell Module Week. Join us tomorrow for Quick-Hits Friday. <\/p>\n

If you want to know exactly what we will be discussing tomorrow, follow us on Twitter<\/a> or Facebook<\/font><\/a>. 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<\/font><\/a>. See you tomorrow. Until then, peace.<\/p>\n

 \nEd Wilson and Craig Liebendorfer, Scripting Guys<\/span><\/b><\/p>\n

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

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

  Hey, Scripting Guy! I am still a bit confused about how modules work. Could you give a beginning-to-end scenario and go through the steps of creating a module, installing the module, and then using the module? — SL   Hello, SL. Microsoft Scripting Guy Ed Wilson here. I am sipping a cup of organic […]<\/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,45],"class_list":["post-51513","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-windows-powershell"],"acf":[],"blog_post_summary":"

  Hey, Scripting Guy! I am still a bit confused about how modules work. Could you give a beginning-to-end scenario and go through the steps of creating a module, installing the module, and then using the module? — SL   Hello, SL. Microsoft Scripting Guy Ed Wilson here. I am sipping a cup of organic […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/51513","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=51513"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/51513\/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=51513"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=51513"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=51513"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}