Summary: Microsoft Scripting Guy, Ed Wilson, talks about how to use a Windows PowerShell module.
Hey, Scripting Guy! I found this module in the Scripting Guys Script Repository. Now what do I do?
—SH
Hello SH,
Microsoft Scripting Guy, Ed Wilson, is here. This morning I have been busy booking travel to Madrid, Spain for TechEd 2013. I will have a booth there with the Scripting Wife. In addition, I will be joining the Windows PowerShell team for their instructor led lab—it will be way cool. Air travel these days is so much fun, I genuinely look forward to each upcoming flight. This includes my flight to TechEd 2013 in New Orleans, where you can also find the Scripting Wife and me. (I am also conducting a Windows PowerShell instructor led lab in the big easy.)
Note This is the fourth part of a multipart series about using Windows PowerShell functions and modules. Prior to reading this blog, you should read the previous posts:
- I Found this PowerShell Function—Now What Do I Do? Part 1
- I Found this PowerShell Function—Now What Do I Do? Part 2
- I Found this PowerShell Function—Now What Do I Do? Part 3
What do I do with a module I find?
Let us suppose that I find a module such as the Windows Update PowerShell Module in the Scripting Guys Script Repository. What do I do with it? Well, the first thing I need to do is to download and to install the module. But this is where things are actually a bit confusing. This is because I can put the module anywhere I want to put it. One of the great things about Windows PowerShell modules is that no installer is required. Most modules, in fact, use a simple copy and paste type of installation (the so-called XCOPY deployment, but you do not need to use XCOPY if you do not wish to do so).
Where do I put the module?
There are two places I can put modules so that Windows PowerShell will automatically recognize them, and will automatically import them. These locations are stored in the PSModulePath environmental variable. From a basic categorization standpoint, one is in my profile/home directory, and the other one is in System32. This output on my computer is shown here.
PS C:\> $env:PSModulePath -split ";"
C:\Users\ed.IAMMRED\Documents\WindowsPowerShell\Modules
C:\Windows\system32\WindowsPowerShell\v1.0\Modules\
It requires admin rights to copy something into the System32 folder, and that is where people sometimes place modules that require admin rights. The problem with this location is that when Windows undergoes servicing, it remotes items from the system folders that it does not know about. This means that your admintype of modules can easily become deleted the next time you run Windows update or apply a service pack.
The problem with storing all modules in my profile/home directory location occurs if I am running as a normal user, and then I need to elevate to an account with admin rights so I can run a module that requires admin rights. My profile/home directory is now a NEW location because I am running as a different user. This makes it painful to navigate back to the old user profile location to launch the module manually.
The answer is simple. Modify the $env:PSModulePath location to include an additional folder—either one on a network, or a folder in an easily accessible location. For example, I have a central datafolder that I use to simplify backups (an XCOPY backup, so to speak). I could easily create a central modules folder that is accessible for all users on the computer. This technique is shown here.
PS C:\> $env:PSModulePath = $env:PSModulePath + ';c:\data\modules'
PS C:\> $env:PSModulePath -split ";"
C:\Users\ed.IAMMRED\Documents\WindowsPowerShell\Modules
C:\Windows\system32\WindowsPowerShell\v1.0\Modules\
c:\data\modules
How do I put the module in its location?
Let’s go back to the Windows Update PowerShell Module from the Scripting Guys Script Repository. It is contained in a file called PSWindowsUpdate.zip. I click the PSWindowsUpdate.zip file in the Script Repository, and after I agree to the terms of use, Internet Explorer asks if I want to Open, Save, or Cancel my action. This is shown in the image that follows.
If I select Open, the zipped file opens revealing a subfolder as shown here:
Cool, it seems that all I need to do is to open my module directory and drag the folder from the zipped folder to my module home directory. The problem if I do this is the files in the folder will all be blocked. This is shown in the following image.
I can use Windows PowerShell 3.0 to unblock the files, but it is easier to unblock the files before installation. To do this, save the .zip file, then right-click it to unblock the file prior to extraction. In this way, all the files contained therein are unblocked. However, if I forget to do this, I can use a command such as the following to unblock the files:
PS C:\Users\ed.IAMMRED\Documents\WindowsPowerShell\Modules> gci .\PSWindowsUpdate -Re
curse | Unblock-File
After I copy the unzipped and unblocked Windows PowerShell module files to the module directory, I can import the module and use the cmdlets. Because I am dealing with Windows update, the Windows PowerShell console needs to be elevated. The following error appears if the Windows PowerShell console is not elevated.
After I elevate Windows PowerShell, I use the Import-Module cmdlet to import the module, and I use the Get-Command cmdlet to see what commands are exposed by the module. This is shown here.
Now that I see the commands, I can use them just like any other Windows PowerShell command from any other module. So I can check to see what updates are available via the Get-WUList cmdlet (function) as shown here:
PS C:\> Get-WUList
ComputerName Status KB Size Title
------------ ------ -- ---- -----
EDLT ---H-- KB2694771 5 MB Bing Desktop v1.2
To install an update, I use the Get-WUInstall function, and to hide an update I use the Hide-WUUpdate command. Pipeline support is available.
I can even check to see if a reboot is required as shown here:
PS C:\> Get-WURebootStatus
Reboot is not Required.
SH, that is all there is to using a Windows PowerShell module. Join me tomorrow when I will reveal the 2013 Scripting Games Event 4.
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