Search results for 'app:weblogs' matching tags 'Scripting Guy!' and 'events and monitoring'

Use PowerShell to Perform an Orderly Shutdown of a Server Running Hyper-V

Anonymous — Thu, 21 Feb 2013 06:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, talks about using Windows PowerShell to shut down all virtual machines on a server running Hyper-V prior to shutting down the server.

Hey, Scripting Guy! From time to time I need to shut down one of our servers that is running the Hyper-V role. The problem is that these servers have multiple virtual machines running, and I do not want to crash the virtual machines. So, right now, I use the Hyper-V Manager, target the server running Hyper-V, and right-click every running virtual machine and select Shut Down. I do not mind doing this, but some of the virtual machines are running things like Exchange and it takes them a long time to shut down. So, what should be a simple task of shutting down one of our Hyper-V servers ends up taking nearly an hour—an hour of very boring work, I might add.

—BB

Hello BB,

Microsoft Scripting Guy, Ed Wilson, is here. Well, the snow is all gone. Yep, that is right, we had snow in Charlotte, NC. I am sitting here, sipping a nice cup of tea. I have been experimenting a bit. Today my teapot contains the following recipe: 2 teaspoons (tsp.) of English Breakfast, 1 tsp. of generic green tea, ½ tsp. of organic orange peel, ½ tsp. of licorice root, 1 tsp. of lemon grass, and a crushed cinnamon stick. Let it steep for 5 minutes, and I have a very nice pot of tea. It is sweet enough that I feel it needs no sweetener whatsoever.

Note In this post, I am using the cmdlets from Windows Server 2012 and the Hyper-V module. I obtained this module on my computer running Windows 8 by downloading and installing the RSAT tools. The Windows 8 RSAT tools are available from the Microsoft Download Center.

Find all running virtual machines

BB, the first thing you need to do is to use the Get-VM cmdlet and find all virtual machines that are running on the remote host. To do this, use the Get-VM and pipe the results to the Where-Object cmdlet and filter out for a state that is equal to running. It is not as difficult as it may sound. The command is shown here.

$runningVM = Get-VM -ComputerName $vmhost| where state -eq 'running'

Because you more than likely have more than a single virtual machine running on your remote Hyper-V server, I use the ForEach language statement to walk through the collection of virtual machines that I store in the $RunningVM variable. Inside the loop, I create a WMI Event that uses the Win32_ComputerShutdownEvent WMI class to let me know when each virtual machine shuts down. This portion of the code is shown here.

foreach ($cn in $runningVM)

{

Write-Debug "registering shutdown event for $($cn.name)"

-SourceIdentifier $cn.name.tostring()

Once I have registered the event, then I call the Stop-Computer cmdlet to shut down the virtual machine. This code is shown here.

Write-debug "Shutting down $($cn.name)"

Stop-Computer -ComputerName $cn.name -Force

Because I registered a win32_ComputerShutdownEvent for the virtual machine, an event triggers after the virtual machine shuts down. To pick up this event, I use the Wait-Event cmdlet. Once the computer shuts down, the event triggers. This code is shown here.

Write-Debug "Waiting for shutdown to complete"

Wait-Event -SourceIdentifier $cn.Name.ToString()}

After all of the virtual machines are shut down, it is time to shut down the Hyper-V host computer (the one that hosts all of the virtual machines). To do this, I use the Stop-Computer cmdlet. This is shown here.

Write-Debug "Shuting down $vmhost"

Stop-Computer -ComputerName $vmhost -Force

Monitor progress of the shutdown

Because I am watching the shutdown of the systems remotely, and I want to know what is happening, I decided to add a series of Write-Debug statements. This is extremely easy to use, and when the script runs without the –debug switch only the default output appears. But when the script runs with the –debug switch, it displays each statement and prompts for the action to take place. This is an interactive type of experience, and it may not be what you want. If you are just wanting more information about each statement without the prompt, then use the Write-Verbose cmdlet instead of Write-Debug. They both work the same—I get them for free as long as I add [cmdletbinding()]

Note During testing, I noticed that sometimes the script would appear to hang. This happens when the virtual machine stops more quickly than I am able to press “y” to confirm the next step, and therefore, the Wait-Event is waiting for an event that has already occurred.

After testing, I decided I was tired of typing “y” all the time, and so I did a global find and replace of Write-Debug with Write-Verbose. I also decided I needed to remove lingering event objects. So I added the following code.

Get-Event -SourceIdentifier $cn.name.Tostring() | Remove-Event

The revised script is shown here.

[cmdletbinding()]

Param($vmhost = 'hyperv2')

Write-Verbose "getting running VM's on $vmhost"

$runningVM = Get-VM -ComputerName $vmhost| where state -eq 'running'

foreach ($cn in $runningVM)

{

Write-Verbose "registering shutdown event for $($cn.name)"

-SourceIdentifier $cn.name.tostring()

Write-Verbose "Shutting down $($cn.name)"

Stop-Computer -ComputerName $cn.name -Force

Write-Verbose "Waiting for shutdown to complete"

Wait-Event -SourceIdentifier $cn.Name.ToString()

Get-Event -SourceIdentifier $cn.name.Tostring() | Remove-Event}

Write-Verbose "Shuting down $vmhost"

Stop-Computer -ComputerName $vmhost -Force

When I run the script now, the following is shown.

BB, that is all there is to using Windows PowerShell to shut down your virtual machines and then to shut down your Hyper-V server. Join me tomorrow when I will talk about more cool 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

Use PowerShell to Create a Permanent WMI Event to Launch a VBScript

Anonymous — Fri, 20 Jul 2012 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, discusses creating a permanent WMI event registration to monitor for new files and clean up the file names.

Microsoft Scripting Guy, Ed Wilson, is here. I just booked the room for the Atlanta (Alpharetta) PowerShell Saturday. This will be PowerShell Saturday event #003, and it will be held on Saturday (of course) on October 27 at the Microsoft Office in Alpharetta, Georgia in the United States. The event is not even up on the PowerShell Saturday page yet, but I thought you might like to get it on your calendars. Of course, the PowerShell Saturday event in Charlotte, North Carolina page is up, as are the abstracts for the sponsors, the speakers, and presentations. Keep your eyes and ears open because the registration site will go live soon, and there are only 200 tickets available. PowerShell Saturday in Columbus Ohio sold out in 13 days, so you will need to be quick if you want to attend this high-profile event.

Creating a permanent WMI event to launch a VBScript…

…that launches a Windows PowerShell script…
…that cleans up a folder of file names with leading spaces upon their arrival…

Note This is the fourth blog in a five part series about monitoring a folder for the creation of files that have leading spaces in the file names. On Monday, I wrote Use PowerShell to Detect and Fix Files with Leading Spaces, the scripts from that blog will be used today and again on Friday. On Tuesday, I wrote Use PowerShell to Monitor for the Creation of New Files. This blog talks about creating a temporary WMI event to monitor for the creation of files in a particular folder (a query that is crucial to Friday’s blog). On Wednesday, I wrote about using a VBScript script to launch a Windows PowerShell script in How to Use VBScript to Run a PowerShell Script. The reason for this blog is that the WMI class that is used for the permanent event consumer uses a VBScript script and not a Windows PowerShell script.

On Thursday, I took a step back and installed the WMI Administrative Tools, and I examined the parts of a permanent WMI event registration. The blog Using the WMI Admin Tools to Check on Permanent Events is a great tutorial. From a reference perspective, you should check out the An Insider’s Guide to Using WMI Events and PowerShell. This guide is a great reference, and it provides great assistance for understanding this powerful technology.

One thing you should monitor, if you will pardon the pun, when designing and implementing permanent WMI event registrations is the fact that they have a lot of moving parts, and they can be rather complicated. You must test your design and your implementation in a lab environment that closely emulates your actual production systems before implanting any of these techniques.

When I was creating the Windows PowerShell script for today’s blog, I actually ended up writing five separate scripts. The scripts are listed here. For ease of access, all five scripts are uploaded to the Script Center Script Repository.

The first script is one that removes the permanent event registrations.
The second script is a stripped down script to create my test files.
The third script is the VBScript that is called by the permanent event registration.
The fourth script is the Windows PowerShell script that is launched to clean up the files.
The fifth script (the most complicated of all) is the one that does the actual WMI permanent event registration.

Avoid setting a short within value

When creating your WMI event query, make sure that you do not set a value of less than 30 (seconds) when going into production. It is common in testing, to set this value to 5 (seconds); but for production, never go less than 30 (seconds). Here is the WMI query that is used in the Create Permanent Event Consumer script.

$query = @"

Select * from __InstanceCreationEvent within 30

where targetInstance isa 'Cim_DirectoryContainsFile'

and targetInstance.GroupComponent = 'Win32_Directory.Name="c:\\\\test"'

Note I discussed this query and the use of the Here-String for formatting the query in Use PowerShell to Monitor for the Creation of New Files.

What happens if you use within 5 in your query? Well, for one thing, Windows PowerShell polls every five seconds to see if there is a change. To see this behavior, I enabled the WMI-Activity trace log in the Event Viewer. One of the events is shown here.

To see the impact, of this, I used the following Windows PowerShell query to review these events.

Get-WinEvent -LogName *wmi-activity* -Force -Oldest | where { $_.id -eq 1 -AND $_.message -match 'select'} | select -Last 20 | ft timecreated, message –AutoSize

By using Windows PowerShell, I can easily see that the WMI query is executing every 5 seconds. (This is NOT the sort of thing you want to do on a heavily loaded production server.) The query and the results from the query are shown here.

Creating the three essential parts to the script

There are three essential parts to a permanent WMI event registration. These were discussed in yesterday’s Hey, Scripting Guy! Blog, Using the WMI Admin Tools to Check on Permanent Events. The first item required is the __EventFilter. The following code does this. (Keep in mind that the new instance of the __EventFilter is created in the root\subscription WMI namespace. But the arguments to this state that the EventNameSpace is in root\cimv2. The reason is that the class being used, Cim_DirectoryContainsFile, resides in root\cimv2.)

$filterPath = Set-WmiInstance -Class __EventFilter `

-ComputerName $computer -Namespace $wmiNS -Arguments `

@{name=$filterName; EventNameSpace=$filterNS; QueryLanguage="WQL";

Query=$query}

The second part is the ActiveScriptEventConsumer. This portion of the script fills out the properties of the ActiveScriptEventConsumer. The three essential portions are the name of the consumer, the script file, and the script engine. Note that the only engine supported is the VBScript scripting engine.

$consumerPath = Set-WmiInstance -Class ActiveScriptEventConsumer `

-ComputerName $computer -Namespace $wmiNS `

-Arguments @{name="CleanupFileNames"; ScriptFileName=$scriptFileName;

ScriptingEngine="VBScript"}

Finally, the last part is the __FilterToConsumerBinding. When this part is configured properly, the green check mark appears in the WMI Administrative Tools as shown yesterday. This portion of the script is really easy. All that is required is to bind the filter and the consumer together as shown here.

Set-WmiInstance -Class __FilterToConsumerBinding -ComputerName $computer `

-Namespace $wmiNS -arguments @{Filter=$filterPath; Consumer=$consumerPath} |

out-null

When the CreatePermenantEventToMonitorForNewFilesAndStartScript.ps1 script runs, no output appears. This is where using the WMI Administrative Tools comes in useful (see Using the WMI Admin Tools to Check on Permanent Events).

Now to test the script, I create some new files in my test folder by using the CreateTestFiles.ps1 script. The newly created files are shown here.

I have to move rather quickly, because I only have a maximum of 30 seconds before the event fires. Here is the cleaned up folder after the event fires.

Clean-up work

I have mentioned before, that when creating a script that makes changes to system state, it is always a good idea to also write a script to do the clean-up work. This is especially true when you are doing demos, or as an aid while you are composing the script. Here is my very simple clean-up script. The thing to keep in mind is that you MUST use a good filter to find your __EventFilter and your __FilterToConsumerBinding, or you will remove things your computer may very well need.

gwmi __eventFilter -namespace root\subscription -filter "name='NewFile'"| Remove-WmiObject

gwmi activeScriptEventConsumer -Namespace root\subscription | Remove-WmiObject

gwmi __filtertoconsumerbinding -Namespace root\subscription -Filter "Filter = ""__eventfilter.name='NewFile'""" | Remove-WmiObject

Logging

I was actually hoping that the WMI-Activity trace log would let me know each time the VBScript ran, but alas, that was not the case. So I added a log to my Windows PowerShell clean-up script that writes the date to a log file. This line is shown here.

"called cleanup script $((get-date).tostring())" >>c:\fso\mylogging.txt

By adding this line to the clean-up files in my Windows PowerShell script, an entry writes to the log file each time the Windows PowerShell script is called from the VBScript.

This ends our WMI Events Week. Join me tomorrow when I will look at the differences in performance between using a literal WMI filter and a WMI wildcard filter. It should be pretty cool.

Ed Wilson, Microsoft Scripting Guy

Using the WMI Admin Tools to Check on Permanent Events

Anonymous — Thu, 19 Jul 2012 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, shows how to use the WMI Administrative tools to check on Permanent WMI events created by Windows PowerShell.

Microsoft Scripting Guy, Ed Wilson, is here. We continue to get new sponsors for the second Windows PowerShell Saturday event that will be held in Charlotte, North Carolina in the United States. The event will occur on September 15, 2012, and registration will be opening soon. I am impressed with the lineup of sponsors. There should be some great giveaways, but most importantly, there are going to be some GREAT speakers—including the Microsoft Scripting Guy (me). You will want to bookmark the PowerShell Saturday website because not only does it contain information about the Windows PowerShell Saturday event in Charlotte, but it will also have information about the event for October in Atlanta.

The first thing you need to do is to download and install the WMI Administrative Tools. The tools are an old HTML application with a very small file size (4.7 MB). In fact, the package is so small, I do not even save it locally. Rather, I run it from the download page. Installation is a simple click, click, and you are done. The only default change I make is that I make the application available for everyone and not just for the installer. The splash screen is shown here.

After you install the tools, you will find them in the WMI Tools folder on your start menu. There are two tools for working with WMI events. The first is the WMI Event Registration tool, and the second is the WMI Event Viewer. Because these are old HTML applications, they use Active X controls that are blocked by default. Therefore, you need to unblock the control before the tool becomes useful. The Allow blocked content message is shown here.

After you open the WMI Event Registration tool and allow the blocked content, you need to select the WMI namespace with which to work. The tool defaults to root\cimv2, but permanent events reside in the root\subscription WMI namespace, and so it is necessary to change that location to see the ActiveScriptEventConsumer. I also create the EventFilter in the root\subscription namespace, so it will not be necessary to switch WMI namespaces to see the EventFilter registration.

Note Keep in mind that this is the WMI Event Registration tool, not the WMI Event Viewer tool. This means that you can edit, delete, and create WMI Event Registrations by using this tool. Unfortunately, there is no Read-only mode for this tool.

The following three things must be present and associated correctly for a permanent WMI event registration to work:

An Event Consumer must be registered.
An Event Filter must be registered.
The Event Consumer must be associated with the Event Filter.

In the image that follows, the ActiveScriptEventConsumer appears in the root\subscription WMI namespace. Notice in the right pane, a green check mark appears next to the __EventFilter class with the instance name of “NewFile”. The green check mark appears under the column that states that it is registered. This image illustrates the Event Consumer to Event Filter binding.

To dig into the details of the ActiveScriptEventConsumer, right-click it in the WMI Event Registration pane. Check out the following:

The Script File Name. It should point to a VBScript file that is accessible to the event consumer.
If you are not using a script file, you can instead type the text of the script command in the Script text box. This is a great way to make a permanent event consumer portable (so that it does not rely on an external file).
The name of the ActiveScriptEventConsumer and the path and the relative path.

These properties are shown in the image that follows.

To review the Event Filter, use the Select arrow to choose Filters. Expand the __EventFilter node and ensure that the EventConsumerClass associates with the __EventFilter. To do this, look for the green check mark under the Reg column. In addition, make sure that the Instance name matches the name of the ActiveScriptEventConsumer detailed earlier. This result is shown here.

To check the properties of the __EventFilter, right-click __EventFilter in the left column, and then click Edit Instance Properties from the Action menu. From here, you will want to check the following items:

The event namespace
The name of the Event Filter
The query being utilized
The namespace of the event filter, in addition to the Path and the RelPath properties

These properties are shown in the image that follows.

When all three items related to permanent WMI events are checked, it is time to proceed to testing. This will be the subject of tomorrow’s blog.

That is all there is to using the WMI Administrative Tools to monitor for new WMI events. I invite you to join me tomorrow when I wrap up this five part series and discuss creating a permanent WMI event via a Windows PowerShell script that will monitor for new files created in a folder. If the file name has spaces at the beginning, it will automatically rename the file. It will be an exciting conclusion to an exciting week. So stay tuned, same script time, same script station (yes, the Scripting Wife and I went to see Batman). Take care.

Ed Wilson, Microsoft Scripting Guy

How to Use VBScript to Run a PowerShell Script

Anonymous — Wed, 18 Jul 2012 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, shows you that it's easier than you think to use VBScript to run a Windows PowerShell script.

Microsoft Scripting Guy, Ed Wilson, is here. Things are really heating up around here—and I am not just talking about the hot, humid weather down in Charlotte, North Carolina in the United States. First, I am busily getting ready for my trip to Seattle, Washington next week. I will be speaking about using Windows PowerShell 3.0 to manage the remote Windows 8 desktop to a bunch of Microsoft people from all over the world. The event (called TechReady 15) is like TechEd, only it is only for Microsoft employees. Nevertheless, in every other fashion, including the size and scope of the event, it is like TechEd. I really look forward to speaking at this event, because it is an honor to get to speak to so many smart people, and it is a great chance to see my friends from all over the world.

The second thing that is exciting are Windows 8 (which I have been running on my production machine for some time) and Office 15 (which I have just installed on my production machine). It is sooo cool, and is powerful, simple to use, and fun. Often powerful and simple do not go together in the computing world. This time, I think we did it right. The Scripting Wife is absolutely chomping at the bit to get a new slate device. I agreed to get her one for the holidays, but she wants it NOW!

The third thing that is super exciting is Windows PowerShell Saturday on September 15 at the Charlotte Microsoft office. We have just about finalized the schedule, and we have all the speakers lined up. It will be a super cool event. Keep watching, because we will be opening registration very soon, and expect it to sell out within days. We have to limit the attendance to 200 people, so you will want to ensure that you are watching for the announcement. The announcement of the opening of registration will take place on Twitter, then on Facebook on the Scripting Guys Facebook site, and then on the Scripting Guys blog, and finally on the Learn PowerShell page. So this would be a good time to get a twitter account and start following @ScriptingWife and @ScriptingGuys. By the way, I love the Rowi app on Windows 8.

Creating a VBScript to run Windows PowerShell

When creating a permanent WMI event consumer that uses the ActiveScriptEventConsumer WMI class, you need to use VBScript as the script type. This is because ActiveScriptEventConsumer does not know how to run a Windows PowerShell script. This is not a huge problem, however, because writing a VBScript script to launch a Windows PowerShell script is very easy when you know the secrets.

Note This is the third blog in a five part series about monitoring a folder for the creation of files that have leading spaces in the file names. On Monday, I wrote Use PowerShell to Detect and Fix Files with Leading Spaces, and the scripts from that blog will be used today and again on Friday. On Tuesday, I wrote Use PowerShell to Monitor for the Creation of New Files. This blog talks about creating a temporary WMI event to monitor for the creation of files in a particular folder. This query is crucial to Friday’s blog.

There are two methods available from the WshShell Object to launch other programs. These methods are the Exec method and the Run method. For my purpose, I use the Run method. It takes two lines of VBscript code; therefore, I use Notepad to create the script. Remember to save it as a .vbs file. The script is shown here.

LaunchPowerShell.VBS

Set objShell = CreateObject("Wscript.shell")

objShell.run("powershell -noexit -file c:\fso\CleanupFiles.ps1")

The first line of code creates the WshShell object, and it stores the returned object in the objShell variable. This line is shown here.

Set objShell = CreateObject("Wscript.shell")

The second line of code runs the command. The syntax of this command is critical. It is a good idea to use the Start / Run command to practice the syntax before embedding it in the VBScript script. Here is an example of using the Run command to practice the syntax.

If you need to bypass the execution policy, you would add that switch to the command as well. The syntax to bypass the execution policy is shown here.

powershell -executionpolicy bypass -noexit -file c:\fso\helloworld.ps1

It is also possible to run a specific Windows PowerShell command or series of commands from the VBScript script. This technique is shown here.

objShell.run("powershell -noexit -command ""&{0..15 | % {Write-Host -foreground $_ 'Hello World' }}""")

Note Keep in mind that you are writing in VBScript. Therefore, you need to escape the quotation marks with another pair of quotation marks. Also, remember that you use REM to comment out a line, and not the pound sign character (#) that is used in Windows PowerShell.

The CleanupFiles.ps1 script referenced in the VBScript script is the Get-FilesWithLeadingSpaces function from Monday’s blog, Use PowerShell to Detect and Fix Files with Leading Spaces. I removed it from the function and placed it in a file to make it easier to call from within the VBScript script. The CleanupFiles.ps1 file is shown here.

CleanupFiles.ps1

Param(

[string]$path = "c:\test",

[switch]$rename = $true

)

Get-ChildItem -Path $path -Recurse |

foreach-object -Begin {$count = 0} -process {

if($_.name.length -ne $_.name.trim().length)

{

if($rename)

{

Rename-Item -Path $_.fullname -NewName ("{0}{1}{2}" -f `

$_.basename.trim(),$count,$_.extension)

$count++

}

else

{"$($_.basename) contains a leading space"}} }

By using the New-FilesWithLeadingSpaces function from Monday, I create 10 new files with leading spaces in the names in a folder named test. These newly created folders are shown here.

Now, I want to try out my VBScript script to see if I can run it, and cause it to launch the Windows PowerShell script to clean up the folder. I open a command prompt, and drag the VBScript script to the command line. The command prompt is shown here.

When I run the script, a Windows PowerShell console appears, but it does not look like it really did anything. Here is the newly appearing Windows PowerShell console.

But when I go to the c:\test folder, I see that all the files are fixed. This is shown here.

That is all there is to using VBScript to run a Windows PowerShell script. WMI Event Monitoring Week will continue tomorrow when I will talk about using the WMI admin tools to monitor for newly arriving events.

Ed Wilson, Microsoft Scripting Guy

Use PowerShell to Monitor for the Creation of New Files

Anonymous — Tue, 17 Jul 2012 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, shows how to use Windows PowerShell to monitor for the creation of new files.

Microsoft Scripting Guy, Ed Wilson, is here. Yesterday’s email from KS about his problems with files that contain leading spaces in them got me thinking. Although running a script on demand to find and rename files in a folder might work, it would be better to use an event to monitor the folder for newly created files. Then if the files match the naming pattern discovered yesterday, rename them by using the procedure from the script I posted yesterday in Use PowerShell to Detect and Fix Files with Leading Spaces.

Note For more information about WMI event driven scripts, see An Insider’s Guide to Using WMI Events and PowerShell.

Today I am going to develop a WMI event query to detect newly created files in a particular folder. Then I will use this WQL event query tomorrow to create a permanent WMI event consumer. In fact, whenever I am creating a permanent WMI event consumer, I always test it out as a temporary event consumer first. Creating a temporary event consumer with Windows PowerShell 2.0 is really easy, so it only makes sense to take this first step.

Creating a WMI WQL event query

The hardest part of creating a WMI WQL event query is, well…just about everything. This stuff does not make much sense. Luckily, if you have WQL event query from VBScript or some other language, it is not too difficult to migrate the query to Windows PowerShell.

When you start trying to do this, however, you run into weird quoting rules that only make a confusing situation more confusing. Luckily, Windows PowerShell can bring some sanity to this part of the process. The secret is to use a here-string. Here-strings are really finicky (they make Morris the Cat seem like an omnivore). The basic syntax is to use a variable to hold the resulting here-string. The here-string begins with an ampersand and an opening quotation mark: @". Everything inside the here-string is interpreted literally so you do not need to worry with escaping special characters or quotation marks or any of that stuff. The here-string closes with a closing quotation mark ampersand: "@.

There are two rules that you must follow:

Immediately after the opening tag @", hit ENTER. Do not press the spacebar and then ENTER; you need the return right after the @".
The closing tag ("@) must be in position 1 of its own line. You cannot place it at the end of your last line of text, nor can you indent to make things “line up.” It must be in the first position of its own line.

I referred to an old Hey Scripting Guy! Blog, How Can I Automatically Run a Script Any Time a File is Added to a Folder, which was written nearly eight years ago in VBScript. Guess what? The query was just the thing I needed to refresh my memory for creating my new query. Here is the VBScript query from that blog.

("SELECT * FROM __InstanceCreationEvent WITHIN 10 WHERE " _

& "Targetinstance ISA 'CIM_DirectoryContainsFile' and " _

& "TargetInstance.GroupComponent= " _

& "'Win32_Directory.Name=""c:\\\\scripts""'")

You can see where the use of a here-string vastly simplifies things by allowing me to forget about line continuation and having to escape quotation marks and other things. But also you can see how having a nice reference query, even from an eight-year old VBScript script, is also beneficial.

Note This is ONE of the major reasons I insisted on migrating all of the old Hey Scripting Guy! Blogs to the new Hey, Scripting Guy! Blog format four years ago when I became the Scripting Guy. I knew that a lot of that old code was easily adaptable to Windows PowerShell and would be useful for years to come.

The WQL query itself is not too horribly bad. It begins by selecting everything from the __InstanceCreationEvent WMI class. This class is a generic event class, and it will monitor for new instances of “stuff.” It can be anything from a new entry in an event log to a new file. The problem with monitoring for a newly created file is that a file must reside somewhere—for example, inside a directory. To find a file in a directory by using WMI means that we need to use an association WMI class.

The Cim_DirectoryContainsFile WMI class associates files and directories. When working with association classes, there is always a property that relates one to the other. Here we are looking for the GroupComponent portion of the association. GroupComponent is an instance of the Win32_Directory WMI class. Because we are interested in a particular directory, we need to use the Key property for GroupComponent. Here, the key is the name of the folder. The name of the folder uses POSIX notation; therefore, it requires \\\\ (four back slashes). The query is shown here.

$query = @"

Select * from __InstanceCreationEvent within 10

where targetInstance isa 'Cim_DirectoryContainsFile'

and targetInstance.GroupComponent = 'Win32_Directory.Name="c:\\\\test"'

Register the WMI event

Now I need register the WMI event. In Windows PowerShell 2.0 and Windows PowerShell 3.0, this is really easy. I use the Register-WmiEvent cmdlet and specify the WQL query. I also need to create a value for the SourceIdentifier property so I can monitor the job. Here, I register the WMI event by using the query contained in the $query variable, and I specify a SourceIdentifier of MonitorFiles.

Upon registering the event, I can do any number of things. The easiest thing to do is to wait for the event to occur. The Wait-Event cmdlet will wait for the event that is identified by the SourceIdentifier to trigger. After it does, I store the generated event in the $fileEvent variable as shown here.

$fileEvent = Wait-Event -SourceIdentifier "MonitorFiles"

Once again, I could do anything I want to do upon notification that an event triggers. Here, I simply display the complete path to the newly created file. I will use this information tomorrow in my follow-up to today’s blog. Notice that the $fileEvent variable contains a rich object. You might want to play around with Get-Member to explore this object.

$fileEvent.SourceEventArgs.NewEvent.TargetInstance.PartComponent

When the script runs, it waits for an event to trigger. This behavior is shown in the image that follows.

When I create a file in the c:\test folder, within 10 seconds the temporary event consumer detects the presence of the newly created file, and Wait-Event returns the event to the $fileEvent variable. The script then displays the path to the newly created file. The image that follows illustrates the Windows PowerShell ISE following the generation of the new event.

Clean up after creating a temporary event subscriber

If you attempt to run the script a second time, you will more than likely receive errors. The error is because the event SourceIdentifier “MonitorFiles” already exists. The way to correct this is to unregister the event. You can do this by name, by specifying the SourceIdentifier property of the Unregister-Event cmdlet. But the easier way to do this is to use the Get-EventSubscriber cmdlet, and pipe the event subscriber to the Unregister-Event cmdlet as shown here.

Get-EventSubscriber | Unregister-Event

The unpredictable results portion of the scenario is that one WMI event already exists—the one that generated during testing. It is certainly possible to work with multiple events, but it is also easier to just clean up. The easiest way to do this is to find all of the WMI events by using the Get-Event cmdlet, and then pipe all the found WMI events to the Remove-Event cmdlet. This command is shown here.

Get-Event | Remove-Event

If you are writing a temporary WMI event consumer script, it makes sense to place the two previous commands into a function called something like Remove-WMIEventAndSubscriber. Such a function is shown here.

Function Remove-WMIEventAndSubscriber

{

Get-EventSubscriber | Unregister-Event

Get-Event | Remove-Event

} #end function Remove-WmiEventAndSubscriber

A function such as Remove-WMIEventAndSubscriber makes testing your script inside the Windows PowerShell ISE much easier, and it saves a lot of typing because you reset the environment each time you decide to run an additional test.

That is all there is to using a temporary WMI event to monitor a folder for the creation of a new file. Join me tomorrow for more Windows PowerShell cool stuff.

Ed Wilson, Microsoft Scripting Guy

The Easy Way to Monitor for an IP Address by Using PowerShell

Anonymous — Wed, 20 Jun 2012 05:00:00 GMT

Summary: The Microsoft Scripting Guy, Ed Wilson, shows how to use Windows PowerShell to monitor for acquiring an IP address.

Hey, Scripting Guy! We have a problem. It seems that when people with laptops come into the office, it takes forever for them to obtain network access. On the tool bar, a blue circle of death spins in an infinite loop. When I hover over the circle, it says “identifying network.” There is nothing to identify—it is our corporate network. I recently figured out that the circle is lying to me. It is not really trying to identify the network; but rather, it is waiting on an Internet Protocol (IP) address. I know you can use a ping command to ping forever, but I can never remember the syntax. In addition, it does not really tell me what I want to know. What I really want to know is if the computer has obtained an IP address. Can I use Windows PowerShell to do this?

—MH

Hello MH,

Microsoft Scripting Guy, Ed Wilson, is here. Often when one thinks about monitoring, one turns ones attention to Windows Management Instrumentation (WMI) events. In fact, I recently published Insider’s Guide to Using WMI Events and PowerShell that listed Hey, Scripting Guy! resources for working with this powerful and cool technology. But at times, such an approach is a bit like using a steamroller to make hamburger patties—it might work, but is not necessarily the easiest way to do things.

MH, one easy way to monitor for acquisition of an Internet Protocol (IP) address is to use the range operator and pair it with the ForEach-Object cmdlet. In fact, this technique is one of my top ten favorite Windows PowerShell tricks because it is so flexible and so powerful. My approach here is to do something really easy, really quick, and with minimal typing. My approach is not efficient, elegant, or even “correct” (as far as Windows PowerShell purists go). I would venture there are even easier ways to do this. But the advantage here is that the command is easy to understand, easy to remember, and easy to type.

The command that follows begins by using the range operator to create an array of numbers from 1 through 500. These numbers cross the pipeline one at a time. The ForEach-Object cmdlet calls the ipconfig command once for each number. The results of ipconfig pipe to the Select-String cmdlet. Select-String displays only the line of output that contains the letters ipv4. By default, there is no alias for the Select-String cmdlet, but remember that by using Tab Expansion, you can greatly reduce your typing load. The following command illustrates how to use Select-String to retrieve only the line of text containing ipv4.

PS C:\> ipconfig | Select-String ipv4

IPv4 Address. . . . . . . . . . . : 192.168.0.54

OK MH, so I can now find my Internet Protocol (IP) address from ipconfig by using the Select-String cmdlet. The next thing, I need to do is to wait for a couple of seconds and clear the Windows PowerShell console host. To do this, I use the Start-Sleep cmdlet (sleep is an alias) and cls (an alias for the Clear-Host function). The complete command is shown here.

1..500 | % {ipconfig | Select-String ipv4 ; sleep 2; cls }

When I run the command, for the first two seconds it displays both the command and the output of the command as shown here.

After the first two seconds of run time, the Windows PowerShell console clears, and only the IPv4 Address displays as shown here.

MH, that is all there is to using Windows PowerShell to monitor for changes in the IP address. Join me tomorrow for more Windows PowerShell cool stuff.

Ed Wilson, Microsoft Scripting Guy

An Insider’s Guide to Using WMI Events and PowerShell

Anonymous — Fri, 08 Jun 2012 05:00:00 GMT

Summary: Microsoft Scripting Guy, Ed Wilson, reviews and discusses Hey, Scripting Guy! Blog posts about WMI events and Windows PowerShell.

Microsoft Scripting Guy, Ed Wilson, is here. Tickets for the Jacksonville IT Pro Camp are rapidly disappearing. If you are anywhere near Jacksonville, Florida on June 16, 2012, you definitely check it out. There are sessions about Windows PowerShell Best Practices, Windows PowerShell Remoting, and general Windows PowerShell admin. Not to mention sessions about Hyper_V, SharePoint, SQL Server, Team Foundation Server, and more. It will be an awesome opportunity to learn from some of the best people in the field. The presenters are Microsoft MVPs, Microsoft PFEs, community leaders, and of course, the Microsoft Scripting Guy.

Today, I want to look at the Hey, Scripting Guy! Blog posts that discuss WMI eventing.

All about WMI eventing

There are two types of WMI events: temporary event consumers and permanent event consumers. The temporary event consumers are events that you set up that will last until you exit the script. A good way to use a temporary event consumer is to start a script that watches something, make a change that changes what is being watched, and then when the event fires, you capture the event and do whatever you wanted to do. Permanent event consumers are written to the WMI repository, survive reboots, and run inside the WMI processes on your computer. There is no script to close, so they run as if they were services. These are used by SCOM and other applications. They are pretty complex, but they are not beyond the realm of people who are experienced in scripting and the use of WMI.

I have been writing about WMI eventing since back in the VBScript days. (In fact, I have an entire chapter about it in my WMI book). I have posts on the Hey, Scripting Guy! Blog from Windows PowerShell 1.0 days. These blogs are not necessarily obsolete because they talk about the underlying eventing .NET Framework classes. In addition, they illustrate the use of generic WMI event classes (the query is the same in Windows PowerShell 2.0 and Windows PowerShell 3.0).

There are two types of WMI event classes: implicit and generic. An implicit event class is really easy to use in Windows PowerShell 2.0 because the class already knows how to do events. A generic WMI event class is more difficult to use because the query is more complex. The nice thing is that the query is basically the same in Windows PowerShell and in VBScript, so you have tons of resources for these types of queries.

Temporary WMI event consumers

All of the following blogs talk about working with temporary WMI event consumers. These are typically set up to monitor a specific item, or items, for only a short period of time.

Using generic WMI classes

How Can I Be Notified When a Process Begins? In this blog, I talk about using a generic WMI class, __InstanceCreationEvent, to monitor for a new process to begin. The blog was written in Windows PowerShell 1.0. It is valuable because I discuss the objects that are involved and show how to create a query by using a generic WMI event class. Please note that there is a Win32_ProcessStartTrace WMI class that makes it easier to monitor for a process to begin. The real value of the blog is in showing how to query a generic class.

How Do I Display a Message and the Time a Process Was Terminated? This blog also uses a generic WMI class, __InstanceDeletionEvent, to monitor when a process goes away. Again, this blog is written in Windows PowerShell 1.0, so you will not need to manually create the EventWatcher class. In addition, there is a Win32_ProcessStopTrace WMI class that is an intrinsic event class. The value is in working with the generic WMI class.

How Can I Back Up a Database’s Data Folder While the Database Is Running? This is an interesting post. It also uses a generic WMI event class, _InstanceModificationEvent. The query is very useful, as is the discussion of the technique actually involved. The technique illustrates doing something that is not easily accomplished via other methods. The script could be simplified by updating to Windows PowerShell 2.0, but this blog is still good.

Overview of writing an event driven script

How Can I Write an Event-Driven Script? This post uses the Register-WmiEvent cmdlet that was introduced in Windows PowerShell 2.0. This blog illustrates the steps involved in writing an event-driven script, and it is a great introduction to the topic.

How Can I Be Notified When a USB Drive Is Plugged into My Computer? This short overview talks about the difference between intrinsic and generic WMI event classes. It illustrates using the Register-WmiEvent and the Get-Event Windows PowerShell cmdlets.

How Can I Retrieve Information About Laptops Changing from Full Power to Minimal Power Usage? This blog follows the prior blog in a series, and it goes into more information about WMI events. The background information presented in the blog is useful for understanding the application of the techniques illustrated in the blog. The use of WMI eventing to monitor changes in power states is also a very good application of the technology.

Specific application useful examples

There are several Hey, Scripting Guy! Blog posts that illustrate using temporary event consumers in a variety of ways. These are intended as “food for thought” types of blogs, and not as specific monitoring solutions.

Can I Be Informed When a Portable Drive Is Added by My Computer? This blog illustrates using the Register-WmiEvent and the Get_Event cmdlets. A temporary event consumer is created that monitors for plugging a USB drive into a computer. The script could be the basis of a more involved script, and the action you decide to take when the drive is inserted or removed is up to you. There are a number of great tips and tricks in this blog.

Can I Format a Portable Drive When It Is Inserted Into a Computer? This blog builds on the previous blog, and it contains a number of extremely useful functions, such as the Test-IsAdministrator function that I wrote for the Windows 7 Resource Kit (admin rights are required to format a drive). The script associated with this blog is quite extensive, and this blog illustrates a number of tips and tricks for working with temporary WMI event consumers.

Can I Start an Event Based on When a Registry Value Is Changed? This blog uses the RegistryValueChangeEvent WMI class to monitor a specific registry key and generate an event when a change takes place. The script also uses the Register-WmiEvent and the Wait-Event cmdlets that were introduced in Windows PowerShell 2.0. This is a great technique when you want to take an action when something in the registry changes. There is also a discussion about the other RegistryEvent WMI classes, and it includes a helpful table to let you know which class you might need.

Can I Use WMI to Determine When Someone Logs Off a User or Shuts Down a Server? This blog uses the Register-WmiEvent cmdlet and the Get-Event cmdlet to monitor the Win32_ShutdownEvent intrinsic WMI class to provide notification. This is an interesting idea that can provide food for thought for some very useful applications.

WMI permanent event consumers

I have five blogs that discuss working with WMI permanent event consumers. The first two are foundational in that I discuss the technology and the parts that are involved in working with event consumers. The last three blogs were written by Trevor Sullivan, and he discusses a module he wrote to make working with permanent event consumers a bit easier.

Learn How to Use VBScript to Create Permanent WMI Events This blog began the Permanent Event Consumer Week. It is foundational, and should be read because it explains the different pieces: the consumer, the event filter, and the filter to consumer binding. You should review this blog carefully if you want to work with WMI permanent event consumers.

Use PowerShell to Monitor and Respond to Events on Your Server The series continues by discussing the different consumer classes. The blog has two extremely powerful scripts: the first script creates a permanent event consumer, the second script reports on permanent event consumers. The blog also illustrates how to remove the event consumers and event filters. The cmdlets used in this blog are Remove-WmiObject and Set-WmiInstance.

Use a PowerShell Module to Work with WMI Permanent Events This blog is written by Trevor Sullivan, and it discusses using his PowerEvents module.

Use the PowerShell WMI Module to Quickly Monitor Events This blog is the second part of using the PowerEvents module.

Monitor and Respond to Windows Power Events with PowerShell In this blog, Trevor talks about using the Win32_PowermanagementEvent intrinsic eventing class and creating a permanent event consumer by using the PowerEvents module. If you do not have the module, you could modify the script in Use PowerShell to Monitor and Respond to Events on Your Server, but it will be more work, and the PowerEvents module works great.

These are the main Hey, Scripting Guy! Blog posts that discuss working with WMI events. I did not review a few others (for examples entries from the Scripting Games) here. To see all the blogs that come up about WMI events, simply click this tag cloud. Join me tomorrow when I will talk about more Windows PowerShell coolness.

Ed Wilson, Microsoft Scripting Guy

Monitor and Respond to Windows Power Events with PowerShell

Anonymous — Tue, 16 Aug 2011 05:00:00 GMT

Summary: Guest Blogger Trevor Sullivan shows how to monitor and to respond to Windows Power events using Windows PowerShell.

Microsoft Scripting Guy Ed Wilson here. Today’s guest blogger is Trevor Sullivan, and he has a fascinating article about responding to power management events. First, a little bit about Trevor.

Trevor Sullivan is a passionate, experienced, and Microsoft-certified IT pro with more than seven years in the industry. Although he is interested in nearly all Microsoft technologies, his primary specialties include:

Design, implementation, and troubleshooting of Microsoft System Center Configuration Manager 2007.
Automation using Windows PowerShell, Windows Management Instrumentation (WMI), Active Directory Services Interface (ADSI), and the Microsoft .NET Framework.

Trevor is a Microsoft-recognized Community Contributor (MCC) and is active in several online communities:

Microsoft TechNet and MSDN discussion forums (he is a moderator on the TechNet Scripting Guys forum).
myITforum mailing lists.
Blogging on WordPress (http://trevorsullivan.net).
Twitter (@pcgeek86).

One of his major achievements is the development and public release of an open-source Windows PowerShell module called PowerEvents. During his personal time, he enjoys studying theology, spending time with his girlfriend, being outdoors, shooting photos, playing video games, testing software, and learning about all sorts of new things.

Take it away, Trevor!

Introduction

Oftentimes, people want to be able to respond to events automatically on their computers: “When <X> happens, I want <Y> to happen in response.” An example of this might be: “If SomeProcess.exe exceeds 50 percent processor utilization for 60 seconds, kill it.” Usually this would require some custom systems monitoring software, but what if I told you that your computer had this functionality built into it already? That’s right, little known to most people is the WMI background service, which provides a robust eventing and event response model.

Although power management hasn’t always been a highlight of the Microsoft Windows operating system (OS), it’s certainly come a long way in Windows 7 and is now quite robust. Sleeping and hibernating in Windows 7 are both quite fast, and resuming from both states is likewise very quick. But what if you want to do something when your computer wakes up? Though this may not be a terribly common scenario, sometimes people have the need to subscribe to this event and perform an action in response to it.

In the remainder of this article, we will take a look at how to subscribe for system-level power management events, and how to respond to them. We will be working with the following technologies:

Windows PowerShell
PowerEvents for Windows PowerShell
Windows Management Instrumentation (WMI)

WMI Power Management events

Microsoft has built a robust power management provider into Windows 7, and thankfully for us, they have exposed its functionality via the WMI service. WMI provides a standards-based interface in the operating system and applications that extend it. Although WMI has suffered from reliability and performance problems in the past—primarily on Windows XP—modern-day hardware combined with the newest Windows 7 operating system is quite reliable. Microsoft has resolved a lot of WMI bugs such that it is a very dependable service.

Power Management WMI Provider

All WMI providers (extensions to WMI) are registered in a particular WMI namespace under the __Win32Provider class. We can ensure that the Windows Power Management provider is registered by running this WMI query from Windows PowerShell:

@(Get-WmiObject -Namespace root\cimv2 -Query "select * from __Win32Provider where Name = 'MS_Power_Management_Event_Provider'").Count

If this query returns a result of “1,” we know that the provider is registered.

Win32_PowerManagementEvent class

The power management provider exposes a single WMI class called Win32_PowerManagementEvent, which is an extrinsic event class. Extrinsic event classes differ from intrinsic event classes in that the events they provide come from an external provider (the Power Management WMI provider), rather than them representing a change to a WMI object.

The Win32_PowerManagementEvent class only has one property that we really care about, which is the EventType property. The possible values for this property are:

Value	Meaning
4	Entering suspend
7	Resume from suspend
10	Power status change
11	OEM event
18	Resume automatic

As you might gather, we are interested in events that have a value of "7," which represents a system resume.

Example Scenario

In this example scenario, we are going to take a look at how to restart a Windows service when the system resumes. Specifically, I recently noticed that the PS3 Media Server software has an issue with power management in that it does not listen for connections upon system resume from Standby/Hibernate. This has reportedly been a problem with Windows 7 Ultimate Edition 64-bit.

To work around this issue, we’ll look at how to restart the PS3 Media Server service each time the computer resumes from a low power state.

Using PowerEvents

The use of the PowerEvents model follows a three-step process:

Create WMI event filter using WQL.
Create an event consumer (response to the event occurrence).
Create a WMI binding between the event filter and the event consumer.

We will cover these three steps individually below.

WQL event filter

First, we need to build an WMI event filter using the WMI Query Language (WQL). WQL is similar to Structured Query Language (SQL), but is much more limited in scope. WQL does not support INSERT, UPDATE, or DELETE statements; it only supports SELECT queries. We’re going to follow the event query template:

select * from <WmiClass> WITHIN <PollInterval> where <Criteria>

In this case, we’re going to use the following values for our event query:

WmiClass = Win32_PowerManagementEvent
PollInterval = 5
Criteria = "EventType = 7"

Our resulting query will look like this:

select * from Win32_PowerManagementEvent WITHIN 5 where EventType = 7

The command we’ll use to create our WMI event filter using the PowerEvents module for Windows PowerShell looks like this:

$Filter = New-WmiEventFilter -Name SystemResumed -Query "select * from Win32_PowerManagementEvent where EventType = 7"

We store the filter object in a Windows PowerShell variable for later use in the event binding.

More information about WMI event queries can be found in the PowerEvents documentation. The PDF is located in the Documentation folder of the PowerEvents download. This document includes information about how to test your WMI event query using the wbemtest.exe utility, before creating the permanent event registration to reduce troubleshooting hassle.

Event consumer

Now that we have created (and tested, right?) the event filter, we need to create an event consumer. In this example, we’ll use a Windows PowerShell script to stop and start the PS3 Media Server service (short name: PS3 Media Server). The script itself contains this code:

$ServiceName = $args[0]

Add-Content -Path 'c:\Restart Service.log' -Value "Service name is: $ServiceName"

$Service = @(Get-WmiObject -Namespace root\cimv2 -Class Win32_Service -Filter "Name = '$ServiceName'")

Add-Content -Path 'C:\Restart Service.log' -Value "Found $($Service.Count) instances of '$ServiceName' service"

$Result = $Service[0].StopService()

Add-Content -Path 'c:\Restart Service.log' -Value "Stopped service with result: $($Result.ReturnValue)"

Start-Sleep 4

$Result = $Service[0].StartService()

Add-Content -Path 'c:\Restart Service.log' -Value "Started service with result: $($Result.ReturnValue)"

Add-Content -Path 'c:\Restart Service.log' -Value "Exiting restart service script"

Save this code in a file called c:\windows\temp\Restart Windows Service.ps1.

To create the event consumer object in WMI, we’ll use the following command:

$Consumer = New-WmiEventConsumer -Verbose -Name SystemResumedRestartService -ConsumerType CommandLine -CommandLineTemplate "powershell.exe -command `". '$($env:WinDir)\temp\Restart Windows Service.ps1' 'PS3 Media Server'`""

This command creates a command-line consumer — that is to say, we want to call a command-line utility in response to the event that occurs. We give it a friendly name so that we know what it runs in response to, and what it does in response to the event: SystemResumedRestartService. Then we use the CommandLineTemplate parameter to specify the command line we want to execute in response to the event. In this case, we’re calling Windows PowerShell and passing it our script file via the -command switch along with an argument to the script file. We use script arguments to make our script dynamic. All we have to do to change the service that gets restarted is change the parameter that we’re passing to it. We don’t have to touch the script itself at all.

Important Make sure you have configured your Windows PowerShell execution policy to allow execution of script files; otherwise, the event consumer will fail. Run Windows PowerShell with your administrative token and use this command: Set-ExecutionPolicy Unrestricted.

WMI event binding

Finally, now that we have created our event filter and event consumer, all we have to do to initiate the flow of events is bind them together. We’ve got the filter and consumer stored in variables called $Filter and $Consumer, so all we have to do is call this command:

New-WmiFilterToConsumerBinding -Filter $Filter -Consumer $Consumer

Testing

And that’s it! We’re done. Now that all the WMI objects have been created, all we have to do is suspend and resume our workstation to test the process. After the system is restarted, we should see a c:\Restart Service.log file created. Check this log to ensure that the service you specified in the event consumer command-line was properly stopped and started.

Conclusion

This article has demonstrated the use of the PowerEvents module for Windows PowerShell to create an event listener (filter)/responder (consumer) for wake-from-low-power-state events. Although this particular example restarts a Windows service in response to such an event, you can use your creativity to come up with other tasks you might need to fire off at the same occurrence.

Note For more information about working with permanent and temporary WMI events, see this collection of Hey, Scripting Guy! Blog posts. This collection includes a post about using VBScript to create permanent WMI events. This post is important because it discusses the basics of permanent WMI events. Next, I talk about using Windows PowerShell to monitor and to respond to events on the server. This post continues the discussion about permanent WMI events. This is followed by the first of two articles from Trevor that talk about his Windows PowerShell module to work with WMI permanent events. The second Trevor article in the series talks about using the Windows PowerShell WMI event module to quickly monitor events.

Thanks Trevor for an interesting article, and for writing your Windows PowerShell module for working with WMI Permanent Events.

Ed Wilson, Microsoft Scripting Guy

Use PowerShell to Troubleshoot Software Installation

Anonymous — Wed, 13 Jul 2011 05:00:00 GMT

Summary: Use Windows PowerShell to troubleshoot software installation.

Hey, Scripting Guy! I am having a problem troubleshooting the installation of an MSI package. I am using Group Policy to deploy the MSI package, and on some computers, it seems to work, but on other computers it fails. After having read your most recent series of articles about troubleshooting Windows, I thought I could use a trace log, but after spending more than an hour trying to click all of those little folders (why is there no search on the log name?), I could not find a trace log that seemed to make sense. Anyway, I guess I am asking you how to troubleshoot remote installation of a MSI package. Hope you can help.

—LT

Hello LT,

Microsoft Scripting Guy Ed Wilson here. This morning, the Scripting Wife and I got to do something we have been looking forward to for nearly two months. When we were at Tech∙Ed 2011 in Atlanta, we got to meet a couple of scripters that work for a company that has a headquarters in the Charlotte area. We exchanged email, and this morning the Scripting Wife and I went to their office and made a three-hour “Introduction to Windows PowerShell” presentation. It was a lot of fun. One of the questions they had was related to troubleshooting remote systems.

LT, you are not alone in your queries. In addition to the customer I was talking to this morning, there was also a comment on Monday’s blog post from Klaus Schulte (winner of the Beginner division of the 2011 Scripting Games) asking about troubleshooting installation packages.

LT, there is a search for trace logs. It is called Windows PowerShell. I have given up attempting to navigate through the hundreds of logs in all the different folders (there are 492 logs on my Windows 7 Ultimate workstation). Instead, if I am searching for a log related to something, I use Windows PowerShell.

In Saturday’s Weekend Scripter article, I talked about working with Event Tracing for Windows (ETW) logs. I discussed how to enable and disable the logs, and how to use the Get-WinEvent cmdlet to find and to read the trace. Monday, I continued the ETW discussion by examining the datetime stamp that is generated for each event. Yesterday, I explored parsing the message property of the WMI Activity Trace log.

If I do not supply a value to the listlog parameter, an error appears. If I provide the name of a specific log, certain information about the log returns. If I use the * wildcard character, information about every log on the system is displayed in the Windows PowerShell console. If I use a more comprehensive wildcard character pattern, I can limit the number of logs that return. An example of searching for trace logs that relate to install is shown here:

PS C:\Windows\system32> Get-WinEvent -ListLog *install* -force | select logname

LogName

-------

Microsoft-Windows-AxInstallService/Log

Microsoft-Windows-WPD-ClassInstaller/Analytic

Microsoft-Windows-WPD-ClassInstaller/Operational

I can use the same technique to search for logs that relate to msi. In the following output, only one log relates to MSI, but it is associated with AppLocker. Therefore, it will not pick up any trace information from a generic MSI installation:

PS C:\Windows\system32> Get-WinEvent -ListLog *msi* -force | select logname

LogName

-------

Microsoft-Windows-AppLocker/MSI and Script

At times, either I cannot find a trace log that I like, or I grow impatient from the search and then use one of my favorite tricks: query all the logs at once. Sure, it is inefficient, but if I am working locally, it is not a big deal. However, it can take a very long time for the command to complete (on my workstation, it takes nearly four minutes to complete the command). The thing to keep in mind is that after the first portion of time—it might be seconds or a minute or so depending on how much data you are returning and how recent your time filter is—new information will no longer be returned to the screen. This is the time when the command is continuing to process log files, but there is no longer any data to return even though the filter coming after the command to return all the event logs is still working. The (inefficient) command to return log files that have a timestamp that occurs later than "7/11/11 10:35:08 pm" follows this paragraph. To make the information display a bit better, I send the information to a table. In the following command the Get-WinEvent cmdlet returns all information from all log files. The returned entries are piped to the Where-Object cmdlet (? Is an alias for the Where-Object cmdlet), which filters log entries after a specific time. The results are piped to the Format-Table cmdlet (ft is an alias for Format-Table cmdlet), and three properties are selected. The command is shown here:

Get-WinEvent | ? {$_.TimeCreated -gt "7/11/11 10:35:08 pm" } | ft logname, id, message

The following figure illustrates running the command in the Windows PowerShell ISE and displays the associated output.

If I want to tighten up the output and create a more efficient use of the space in my output pane in the Windows PowerShell ISE, I can add the autosize parameter to the Format-Table cmdlet. In addition, I can display the entire message if I use the wrap parameter. However, when I add these parameters to the previous command, it will take the most of the time (five minutes or so) the command runs before displaying output. This is because to calculate the amount of space to allocate for the columns, Windows PowerShell needs to look at all of the data. This reduces the efficiency of the streaming behavior that I took advantage of earlier. The revised command is shown here:

Get-WinEvent | ? {$_.TimeCreated -gt "7/11/11 10:35:08 pm" } | ft logname, id, message -AutoSize –wrap

Clearly, a more efficient method of working with log files is required.

For more information about using the FilterHashTable parameter, see Use a PowerShell Cmdlet to Filter Event Log for Easy Parsing and Use PowerShell to Parse Saved Event Logs for Errors. For more information about improving the performance of event log queries, see How to Improve the Performance of a PowerShell Event Log Query. For issues surrounding working remotely with Windows Vista and Windows XP event logs, refer to Discover How to Filter Remote Event Log Entries in Windows Vista.

The following table is copied from my Use PowerShell to Parse Saved Event Logs for Errors Hey, Scripting Guy! Blog post from January 2011.

Event Log Viewer name	FilterHashTable parameter key name
Log Name	LogName
Source	ProviderName
Event ID	ID
Level	Level
User	UserID
Op Code	*
Logged	*
Task Category	*
Keywords	*
Computer	N/A use –ComputerName parameter
Details	Data

If I attempt to use my trick of using the Get-Winevent cmdlet to list all log entries, and I use a FilterHashTable to attempt to filter based on time at the Get-Winevent cmdlet instead of on the other side of the pipeline, an error returns that states I must specify either a log, provider, or path. The command and associated error appear here:

PS C:\Windows\system32> Get-WinEvent -FilterHashTable @{StartTime = "7/11/11 10:35:08 pm"}

Get-WinEvent : You must specify at least one Log, Provider or Path key-value pair.

At line:1 char:13

+ Get-WinEvent <<<< -FilterHashTable @{StartTime = "7/11/11 10:35:08 pm"}

+ CategoryInfo : InvalidArgument: (:) [Get-WinEvent], Exception

+ FullyQualifiedErrorId : LogProviderOrPathNeeded,Microsoft.PowerShell.Commands.GetWinEventCommand

I decide to modify the command to use a wildcard character for the logname key for the FilterHashTable. The command works great and returns data nearly immediately:

Get-WinEvent -FilterHashtable @{StartTime = "7/11/11 10:35:08 pm"; LogName = "*"}

The nice thing about the above command is it returns information from multiple logs and multiple providers. This is useful, for example, when troubleshooting installation problems that may be unrelated to the actual installer. To check a specific installation, it may be useful to filter based on not only the time, but also on the provider. For MSI installed software, the provider is the msiInstaller provider. The following command is broken at the pipe character for readability purposes. In reality it is a single command:

Get-WinEvent -FilterHashtable @{StartTime = "7/11/11 10:35:08 pm"; ProviderName = "msiInstaller"} |

ft logname, id, message -AutoSize –wrap

The command and associated output appear in the following figure.

LT, that is all there is to using Windows PowerShell to look at Windows Installer logging. Troubleshooting Windows week will continue tomorrow.

Ed Wilson, Microsoft Scripting Guy

Manage Event Subscriptions with PowerShell

Anonymous — Fri, 17 Jun 2011 05:00:00 GMT

Summary: Bruce Payette shows how to manage event subscriptions with Windows PowerShell.

Microsoft Scripting Guy, Ed Wilson, here. I am really excited about the idea I had for this week, and I hope you will be too. I asked Candace Gillhoolley at Manning Press about posting some sample works from some of the Manning Press library of books. She responded enthusiastically and shared five samples that we will post this week. Today is part two of two parts from Bruce Payette and Windows PowerShell in Action. See yesterday’s blog post for part 1.

Windows PowerShell in Action, Second Edition

By Bruce Payette

The key difference between event-based scripting and traditional procedural scripting is that, instead of an activity being executed as a result of an action in the script, a script (or at least a portion of it) is executed as a result of an action by the system.. In this article based on chapter 20 of Windows PowerShell in Action, Second Edition, author Bruce Payette discusses asynchronous event-handling models in PowerShell. To save 35% on your next purchase use Promotional Code payette22035 when you check out at www.manning.com.

Managing event subscriptions

In this section, you’ll see how to find your event subscriptions and how to remove them when you’re done with them. Being able to remove them is important because event subscriptions persist in the session until explicitly removed.

Listing event subscriptions

Of course, before you can remove a subscription, you have to find it. Windows PowerShell provides the Get-EventSubscriber to do this. Let’s use it to look at the subscription you registered in the previous section (see yesterday’s Hey! Scripting Guy blog):

PS (1) > Get-EventSubscriber

SubscriptionId   : 1

SourceObject     : System.Timers.Timer

EventName        : Elapsed

SourceIdentifier : fca4b869-8d5a-4f11-8d45-e84af30845f1

Action           : System.Management.Automation.PSEventJob

HandlerDelegate :

SupportEvent     : False

ForwardEvent     : False

The Get-EventSubscriber cmdlet returns PSEventSubscriber objects, which have complete information about the registration: the object generating the event, the action to execute, and so on. There are a couple of interesting properties to note in this output. Because you didn’t give the subscription a friendly name using -Source-Identifier when you created it, the Register-ObjectEvent generated one for you. This autogenerated name is the string representation of a GUID, so you know it’s unique (but not very friendly). The other thing to notice is that the action shows up as a PowerShell Job object.

Removing event subscriptions

Now that you can list the event subscriptions, you can set about removing them. The cmdlet to do this is not Unsubscribe-Event because unsubscribe isn’t on the approved verbs list and it’s not what you want to do anyway. You registered event subscriptions with Register-ObjectEvent, so what you need to do is unregister the subscription, which you’ll do with Unregister-Event. The cmdlet noun in this case is Event, not ObjectEvent, because you can use a common mechanism to unregister any kind of event. It’s only the registration part that varies. The rest of the eventing cmdlets remain the same.

When you’re unregistering an event subscription, there are two ways of identifying the event to unregister: by the SubscriptionId property or by the Source-Identifier. The subscription ID is simply an integer that’s incremented each time an event subscription is created. Because you didn’t give your event registration a friendly name, you’ll use the SubscriptionId to unregister it:

PS (4) > Unregister-Event -SubscriptionId 1 -Verbose

VERBOSE: Performing operation "Unsubscribe" on Target "Event

subscription 'timertest2'".

PS (5) >

Note that you included the -Verbose flag in this command so that you could see something happening. Let’s try running the command again

PS (5) > Unregister-Event -SubscriptionId 1

Unregister-Event : Event subscription with identifier '1' does not

exist.

At line:1 char:17

+ Unregister-Event <<<< -SubscriptionId 1

    + CategoryInfo : InvalidArgument: (:) [Unregister-Event

   ], ArgumentException

    + FullyQualifiedErrorId : INVALID_SUBSCRIPTION_IDENTIFIER,

   Microsoft.PowerShell.Commands.UnregisterEventCommand

…and it results in an error. The Unregister-Event cmdlet is silent as long as nothing goes wrong. If something does go wrong, you get an error.

We’ve covered the basics of creating and managing event subscriptions. But before the handlers for these events can do much useful work, they’ll need access to additional information. In the next section, you’ll write more sophisticated handlers and see how they can use the automatic variables provided by the eventing subsystem.

Asynchronous event handling with scriptblocks

In this section, we’ll look at the automatic variables and other features that PowerShell provides to allow scriptblocks to be used as effective event handlers.

Automatic variables in the event handler

In PowerShell eventing, the scriptblock that handles the event action has access to a number of variables that provide information about the event being handled:

$event, $eventSubscriber, $sender, $sourceEventArgs, and $sourceArgs

These variables are described in table 2.

Table 2 The automatic variables available in the event handler scriptblock

Variable	Description
$event	This variable contains an object of type System.Management.Automation.PSEventArgs that represents the event that’s being handled. It allows you to access a wide variety of information about the event, as you’ll see in an example. The value of this variable is the same object that the Get-Event cmdlet returns.
$eventSubscriber	This variable contains the PSEventSubscriber object that represents the event subscriber of the event that’s being handled. The value of this variable is the same object that the Get-EventSubscriber cmdlet returns.
$sender	The value in this variable is the object that generated the event. This variable is a shortcut for $EventArgs.Sender.
$sourceEventArgs	Contains objects that represent the arguments of the event that’s being processed. This variable is a shortcut for $Event.SourceArgs.
$sourceArgs	Contains the values from $Event.SourceArgs. Like any other scriptblock, if there is a param statement, the parameters defined by that statement will be populated and $args will only contain leftover values for which there were no parameters.

Let’s write a quick test event handler to see what’s in the object in $Event. You’ll use the timer event again:

PS (1) > $timer = New-Object System.Timers.Timer -Property @{

>> Interval = 1000; Enabled = $true; AutoReset = $false }

>>

In the event subscription action, you’ll display the contents of the event object:

PS (2) > Register-ObjectEvent $timer Elapsed -Action {

>> $Event | Out-Host

>> }

>>

Id          Name                State      HasMoreData      Location

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

4           9e3586c3-534...     NotStarted False

You’ll start the timer to generate the event:

PS (3) > $timer.Start()

PS (4) >

ComputerName     :

RunspaceId       : 373d0ee9-47a5-4ceb-89e5-61e6389d6838

EventIdentifier : 7

Sender           : System.Timers.Timer

SourceEventArgs : System.Timers.ElapsedEventArgs

SourceArgs       : {System.Timers.Timer, System.Timers.ElapsedEv

entArgs}

SourceIdentifier : 9e3586c3-534b-465a-84b3-7404110a0f12

TimeGenerated    : 8/10/2010 12:17:40 PM

MessageData      :

In this output, you see the properties on the PSEvent object that correspond to the variables listed in table 2. The Timer object that generated the event is available through the Sender property on the object and the $sender variable in the scriptblock.

The PSEvent object also includes context data about the event, including the time the event occurred, the event identifier, and the RunspaceId this event is associated with. The ComputerName property is blank because this is a local event, but, in the case of a remote event, it would contain the name of the computer where the event occurred.

Dynamic modules and event handler state

Because an event can fire at any time, you could never know what variables were in scope and this, in turn, could make it hard to know what state will exist when the action is executed. Instead, you want to be able to run the event handlers in a well-defined, isolated environment. This objective aligns with the design goals for PowerShell modules, so you can leverage this feature by creating a dynamic module for the action scriptblock. The eventing subsystem does this by calling the New-BoundScriptBlockScriptblock() method to attach a dynamic module to the handler scriptblock.

Beyond ensuring a coherent runtime environment for your event handler scriptblock, the module also allows it to have private state. This ability can be quite useful when you’re monitoring a system’s behavior over a period of time. The information can be accumulated privately and then processed once enough samples have been gathered. Let’s look at an example that illustrates how this state isolation works. The following is a trivial example where you maintain a count of the number of timer events fired. Once you reach a predetermined limit, the timer will be stopped. Let’s walk through the example. First, you create the Timer object:

PS (1) > $timer = New-Object System.Timers.Timer -Property @{

>> Interval = 500; AutoReset = $true}

>>

As usual, subscribe to the Elapsed event on the timer:

PS (2) > Register-ObjectEvent -InputObject $timer `

>> -MessageData 5 `

>> -SourceIdentifier Stateful -EventName Elapsed -Action {

>> $script:counter += 1

>> Write-Host "Event counter is $counter"

>> if ($counter -ge $Event.MessageData)

>> {

>> Write-Host "Stopping timer"

>> $timer.Stop()

>> }

>> } > $null

>>

In the handler scriptblock for this event, you’re updating a script-scoped variable $script:counter, which holds the number of times the event has fired. This variable will only be visible within the dynamic module associated with the event, thus preventing your $counter from colliding with any other users of a variable called $counter.

After the variable is incremented, you print the event count and then check to see if the limit has been reached. Notice that you’re making use of the -MessageData parameter to pass the limit to the event handler, which it retrieves from the MessageData property on the Event object. Now start the timer running to see it in action:

PS (3) > $timer.Start()

PS (4) >

PS (5) > Event counter is 1

Event counter is 2

Event counter is 3

Event counter is 4

Event counter is 5

Stopping timer

PS (6) >

As intended, the timer message is displayed five times and then the timer is stopped. This example can easily be modified to, for example, monitor CPU usage or process working sets over a period of time.

Summary

There are two fundamental event types: synchronous and asynchronous. In synchronous events, all activities are synchronized so that no activity is ever interrupted. Asynchronous events execute in a nondeterministic order. To deal with these asynchronous events, PowerShell includes an eventing subsystem that takes care of synchronizing all operations. The core model for eventing in PowerShell is built around the idea of event subscriptions. There are three cmdlets for creating these subscriptions: Get-ObjectEvent, Get-WmiEvent, and Get-EngineEvent for .NET, WMI, and PowerShell engine events respectively.

As part of the event subscription, an action scriptblock may be specified that will be executed when the event is triggered. Context information for the event is made available to the scriptblock through the $Event automatic variable. Some of the properties on the object in $Event are also directly available through additional automatic variables.

Thank you, Bruce.

Well, this concludes an awesome week of guest writers from Manning Press. Join me tomorrow for the Weekend Scripter as I delve into my top ten favorite Windows PowerShell tricks.

Ed Wilson, Microsoft Scripting Guy